diff --git a/.github/scripts/update-homebrew-tap.sh b/.github/scripts/update-homebrew-tap.sh
index d0e28018..5d8f970e 100644
--- a/.github/scripts/update-homebrew-tap.sh
+++ b/.github/scripts/update-homebrew-tap.sh
@@ -34,14 +34,24 @@ sha() {
 
 # --- read checksums ---------------------------------------------------
 
-readonly SHA_DISP_MACOS_ARM="$(sha deepseek-macos-arm64)"
-readonly SHA_TUI_MACOS_ARM="$(sha deepseek-tui-macos-arm64)"
-readonly SHA_DISP_MACOS_X64="$(sha deepseek-macos-x64)"
-readonly SHA_TUI_MACOS_X64="$(sha deepseek-tui-macos-x64)"
-readonly SHA_DISP_LINUX_ARM="$(sha deepseek-linux-arm64)"
-readonly SHA_TUI_LINUX_ARM="$(sha deepseek-tui-linux-arm64)"
-readonly SHA_DISP_LINUX_X64="$(sha deepseek-linux-x64)"
-readonly SHA_TUI_LINUX_X64="$(sha deepseek-tui-linux-x64)"
+# Canonical dispatcher and TUI
+readonly SHA_COD_MACOS_ARM="$(sha codewhale-macos-arm64)"
+readonly SHA_TUI_MACOS_ARM="$(sha codewhale-tui-macos-arm64)"
+readonly SHA_COD_MACOS_X64="$(sha codewhale-macos-x64)"
+readonly SHA_TUI_MACOS_X64="$(sha codewhale-tui-macos-x64)"
+readonly SHA_COD_LINUX_ARM="$(sha codewhale-linux-arm64)"
+readonly SHA_TUI_LINUX_ARM="$(sha codewhale-tui-linux-arm64)"
+readonly SHA_COD_LINUX_X64="$(sha codewhale-linux-x64)"
+readonly SHA_TUI_LINUX_X64="$(sha codewhale-tui-linux-x64)"
+# Legacy shims (removed in v0.9.0)
+readonly SHA_LEG_MACOS_ARM="$(sha deepseek-macos-arm64)"
+readonly SHA_LEG_TUI_MACOS_ARM="$(sha deepseek-tui-macos-arm64)"
+readonly SHA_LEG_MACOS_X64="$(sha deepseek-macos-x64)"
+readonly SHA_LEG_TUI_MACOS_X64="$(sha deepseek-tui-macos-x64)"
+readonly SHA_LEG_LINUX_ARM="$(sha deepseek-linux-arm64)"
+readonly SHA_LEG_TUI_LINUX_ARM="$(sha deepseek-tui-linux-arm64)"
+readonly SHA_LEG_LINUX_X64="$(sha deepseek-linux-x64)"
+readonly SHA_LEG_TUI_LINUX_X64="$(sha deepseek-tui-linux-x64)"
 
 # --- temp dirs --------------------------------------------------------
 
@@ -62,47 +72,81 @@ class DeepseekTui < Formula
 
   on_macos do
     if Hardware::CPU.arm?
-      url "${BASE_URL}/deepseek-macos-arm64", using: :nounzip
-      sha256 "${SHA_DISP_MACOS_ARM}"
+      url "${BASE_URL}/codewhale-macos-arm64", using: :nounzip
+      sha256 "${SHA_COD_MACOS_ARM}"
       resource "tui" do
-        url "${BASE_URL}/deepseek-tui-macos-arm64", using: :nounzip
+        url "${BASE_URL}/codewhale-tui-macos-arm64", using: :nounzip
         sha256 "${SHA_TUI_MACOS_ARM}"
       end
+      resource "legacy-shim" do
+        url "${BASE_URL}/deepseek-macos-arm64", using: :nounzip
+        sha256 "${SHA_LEG_MACOS_ARM}"
+      end
+      resource "legacy-tui-shim" do
+        url "${BASE_URL}/deepseek-tui-macos-arm64", using: :nounzip
+        sha256 "${SHA_LEG_TUI_MACOS_ARM}"
+      end
     else
-      url "${BASE_URL}/deepseek-macos-x64", using: :nounzip
-      sha256 "${SHA_DISP_MACOS_X64}"
+      url "${BASE_URL}/codewhale-macos-x64", using: :nounzip
+      sha256 "${SHA_COD_MACOS_X64}"
       resource "tui" do
-        url "${BASE_URL}/deepseek-tui-macos-x64", using: :nounzip
+        url "${BASE_URL}/codewhale-tui-macos-x64", using: :nounzip
         sha256 "${SHA_TUI_MACOS_X64}"
       end
+      resource "legacy-shim" do
+        url "${BASE_URL}/deepseek-macos-x64", using: :nounzip
+        sha256 "${SHA_LEG_MACOS_X64}"
+      end
+      resource "legacy-tui-shim" do
+        url "${BASE_URL}/deepseek-tui-macos-x64", using: :nounzip
+        sha256 "${SHA_LEG_TUI_MACOS_X64}"
+      end
     end
   end
 
   on_linux do
     if Hardware::CPU.arm?
-      url "${BASE_URL}/deepseek-linux-arm64", using: :nounzip
-      sha256 "${SHA_DISP_LINUX_ARM}"
+      url "${BASE_URL}/codewhale-linux-arm64", using: :nounzip
+      sha256 "${SHA_COD_LINUX_ARM}"
       resource "tui" do
-        url "${BASE_URL}/deepseek-tui-linux-arm64", using: :nounzip
+        url "${BASE_URL}/codewhale-tui-linux-arm64", using: :nounzip
         sha256 "${SHA_TUI_LINUX_ARM}"
       end
+      resource "legacy-shim" do
+        url "${BASE_URL}/deepseek-linux-arm64", using: :nounzip
+        sha256 "${SHA_LEG_LINUX_ARM}"
+      end
+      resource "legacy-tui-shim" do
+        url "${BASE_URL}/deepseek-tui-linux-arm64", using: :nounzip
+        sha256 "${SHA_LEG_TUI_LINUX_ARM}"
+      end
     else
-      url "${BASE_URL}/deepseek-linux-x64", using: :nounzip
-      sha256 "${SHA_DISP_LINUX_X64}"
+      url "${BASE_URL}/codewhale-linux-x64", using: :nounzip
+      sha256 "${SHA_COD_LINUX_X64}"
       resource "tui" do
-        url "${BASE_URL}/deepseek-tui-linux-x64", using: :nounzip
+        url "${BASE_URL}/codewhale-tui-linux-x64", using: :nounzip
         sha256 "${SHA_TUI_LINUX_X64}"
       end
+      resource "legacy-shim" do
+        url "${BASE_URL}/deepseek-linux-x64", using: :nounzip
+        sha256 "${SHA_LEG_LINUX_X64}"
+      end
+      resource "legacy-tui-shim" do
+        url "${BASE_URL}/deepseek-tui-linux-x64", using: :nounzip
+        sha256 "${SHA_LEG_TUI_LINUX_X64}"
+      end
     end
   end
 
   def install
-    bin.install Dir["*"].first => "deepseek"
-    resource("tui").stage { bin.install Dir["*"].first => "deepseek-tui" }
+    bin.install Dir["*"].first => "codewhale"
+    resource("tui").stage { bin.install Dir["*"].first => "codewhale-tui" }
+    resource("legacy-shim").stage { bin.install Dir["*"].first => "deepseek" }
+    resource("legacy-tui-shim").stage { bin.install Dir["*"].first => "deepseek-tui" }
   end
 
   test do
-    system "#{bin}/deepseek", "--version"
+    system "#{bin}/codewhale", "--version"
   end
 end
 EOF
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4203a17c..45c212bd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -38,6 +38,8 @@ jobs:
           components: rustfmt
       - name: Check formatting
         run: cargo fmt --all -- --check
+      - name: Check provider registry drift
+        run: python3 scripts/check-provider-registry.py
       - name: Linux clippy location
         run: echo "Linux clippy/test gates run on CNB for mirrored fix/*, rebrand/*, work/v*, and main branches."
 
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index 53fcd34a..035193ef 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -33,6 +33,10 @@ jobs:
             target: aarch64-unknown-linux-gnu
             binary: codewhale
             artifact_name: codewhale-linux-arm64
+          - os: ubuntu-latest
+            target: riscv64gc-unknown-linux-gnu
+            binary: codewhale
+            artifact_name: codewhale-linux-riscv64
           - os: macos-latest
             target: x86_64-apple-darwin
             binary: codewhale
@@ -54,6 +58,10 @@ jobs:
             target: aarch64-unknown-linux-gnu
             binary: codewhale-tui
             artifact_name: codewhale-tui-linux-arm64
+          - os: ubuntu-latest
+            target: riscv64gc-unknown-linux-gnu
+            binary: codewhale-tui
+            artifact_name: codewhale-tui-linux-riscv64
           - os: macos-latest
             target: x86_64-apple-darwin
             binary: codewhale-tui
@@ -84,8 +92,33 @@ jobs:
             sleep 15
           done
           sudo apt-get install -y libdbus-1-dev pkg-config
+      - name: Install RISC-V cross-compilation toolchain
+        if: matrix.target == 'riscv64gc-unknown-linux-gnu'
+        run: |
+          # Install cross-compiler (available in standard repos)
+          sudo apt-get update
+          sudo apt-get install -y gcc-riscv64-linux-gnu libc6-dev-riscv64-cross
+
+          # Add Ubuntu ports for riscv64 packages
+          . /etc/os-release
+          sudo tee /etc/apt/sources.list.d/riscv64.sources <<SRC
+          Types: deb
+          URIs: http://ports.ubuntu.com/
+          Suites: ${UBUNTU_CODENAME} ${UBUNTU_CODENAME}-updates
+          Components: main universe
+          Architectures: riscv64
+          Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
+          SRC
+          sudo dpkg --add-architecture riscv64
+          sudo apt-get update -o Dir::Etc::sourcelist=/etc/apt/sources.list.d/riscv64.sources -o Dir::Etc::sourceparts=- -o APT::Get::List-Cleanup=0
+          sudo apt-get install -y libdbus-1-dev:riscv64
       - name: Build
         shell: bash
+        env:
+          CC_riscv64gc_unknown_linux_gnu: riscv64-linux-gnu-gcc
+          CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_LINKER: riscv64-linux-gnu-gcc
+          PKG_CONFIG_ALLOW_CROSS: 1
+          PKG_CONFIG_LIBDIR_riscv64gc_unknown_linux_gnu: /usr/lib/riscv64-linux-gnu/pkgconfig
         run: cargo build --release --locked --target ${{ matrix.target }}
       - name: Stage artifact
         id: stage
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b650617c..40ec45dd 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -71,9 +71,15 @@ jobs:
         run: |
           if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
             tag="v${{ inputs.version }}"
-            git fetch --force origin "refs/tags/${tag}:refs/tags/${tag}"
-            sha="$(git rev-list -n 1 "${tag}")"
-            source_ref="${tag}"
+            if git rev-parse "refs/tags/${tag}" >/dev/null 2>&1; then
+              sha="$(git rev-list -n 1 "${tag}")"
+              source_ref="${tag}"
+            else
+              # Tag doesn't exist yet — build from HEAD
+              sha="${GITHUB_SHA}"
+              source_ref="${GITHUB_SHA}"
+              echo "Tag ${tag} not found; building from ${source_ref} @ ${sha}"
+            fi
           else
             tag="${GITHUB_REF_NAME}"
             sha="${GITHUB_SHA}"
@@ -109,6 +115,10 @@ jobs:
             target: aarch64-unknown-linux-gnu
             binary: codewhale
             artifact_name: codewhale-linux-arm64
+          - os: ubuntu-latest
+            target: riscv64gc-unknown-linux-gnu
+            binary: codewhale
+            artifact_name: codewhale-linux-riscv64
           - os: macos-latest
             target: x86_64-apple-darwin
             binary: codewhale
@@ -130,6 +140,10 @@ jobs:
             target: aarch64-unknown-linux-gnu
             binary: codewhale-tui
             artifact_name: codewhale-tui-linux-arm64
+          - os: ubuntu-latest
+            target: riscv64gc-unknown-linux-gnu
+            binary: codewhale-tui
+            artifact_name: codewhale-tui-linux-riscv64
           - os: macos-latest
             target: x86_64-apple-darwin
             binary: codewhale-tui
@@ -204,10 +218,34 @@ jobs:
             sleep 15
           done
           sudo apt-get install -y libdbus-1-dev pkg-config
+      - name: Install RISC-V cross-compilation toolchain
+        if: matrix.target == 'riscv64gc-unknown-linux-gnu'
+        run: |
+          # Install cross-compiler (available in standard repos)
+          sudo apt-get update
+          sudo apt-get install -y gcc-riscv64-linux-gnu libc6-dev-riscv64-cross
+
+          # Add Ubuntu ports for riscv64 packages
+          . /etc/os-release
+          sudo tee /etc/apt/sources.list.d/riscv64.sources <<SRC
+          Types: deb
+          URIs: http://ports.ubuntu.com/
+          Suites: ${UBUNTU_CODENAME} ${UBUNTU_CODENAME}-updates
+          Components: main universe
+          Architectures: riscv64
+          Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
+          SRC
+          sudo dpkg --add-architecture riscv64
+          sudo apt-get update -o Dir::Etc::sourcelist=/etc/apt/sources.list.d/riscv64.sources -o Dir::Etc::sourceparts=- -o APT::Get::List-Cleanup=0
+          sudo apt-get install -y libdbus-1-dev:riscv64
       - name: Build
         shell: bash
         env:
           DEEPSEEK_BUILD_SHA: ${{ needs.resolve.outputs.sha }}
+          CC_riscv64gc_unknown_linux_gnu: riscv64-linux-gnu-gcc
+          CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_LINKER: riscv64-linux-gnu-gcc
+          PKG_CONFIG_ALLOW_CROSS: 1
+          PKG_CONFIG_LIBDIR_riscv64gc_unknown_linux_gnu: /usr/lib/riscv64-linux-gnu/pkgconfig
         run: cargo build --release --locked --target ${{ matrix.target }}
       - name: Rename binary
         shell: bash
@@ -223,6 +261,108 @@ jobs:
         with:
           name: ${{ matrix.artifact_name }}
           path: ${{ matrix.artifact_name }}
+
+  bundle:
+    needs: [build, resolve]
+    if: ${{ !cancelled() && needs.build.result == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.resolve.outputs.source_ref }}
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          pattern: 'codewhale*'
+      - name: Create platform archives
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p bundles/checksums
+          MANIFEST="bundles/checksums/codewhale-bundles-sha256.txt"
+          : > "$MANIFEST"
+
+          bundle() {
+            local platform="$1"   # linux-x64, linux-arm64, macos-x64, macos-arm64, windows-x64
+            local cli_src="$2"    # artifact name for codewhale binary
+            local tui_src="$3"    # artifact name for codewhale-tui binary
+            local ext="$4"        # tar.gz or zip
+            local variant="$5"    # '' (standard) or 'portable' (Windows only, no install script)
+            shift 5
+
+            local dir="bundles/codewhale-${platform}${variant:+-}${variant}"
+            mkdir -p "$dir"
+
+            # Copy binaries, stripping platform suffixes
+            local cli_dst="codewhale"
+            local tui_dst="codewhale-tui"
+            if [[ "$platform" == windows-* ]]; then
+              cli_dst="codewhale.exe"
+              tui_dst="codewhale-tui.exe"
+            fi
+            cp "artifacts/${cli_src}/${cli_src}" "$dir/${cli_dst}"
+            cp "artifacts/${tui_src}/${tui_src}" "$dir/${tui_dst}"
+
+            # Add install script (standard variant only)
+            if [[ "$variant" != "portable" ]]; then
+              if [[ "$platform" == windows-* ]]; then
+                cp scripts/release/install.bat "$dir/"
+                # Convert line endings to CRLF for Windows
+                sed -i 's/$/\r/' "$dir/install.bat" 2>/dev/null || true
+              else
+                cp scripts/release/install.sh "$dir/"
+                chmod +x "$dir/install.sh"
+              fi
+            fi
+
+            if [[ "$ext" == "zip" ]]; then
+              (cd bundles && zip -r "codewhale-${platform}${variant:+-}${variant}.zip" "codewhale-${platform}${variant:+-}${variant}/")
+            else
+              tar -czf "bundles/codewhale-${platform}${variant:+-}${variant}.tar.gz" -C bundles "codewhale-${platform}${variant:+-}${variant}/"
+            fi
+
+            local archive="codewhale-${platform}${variant:+-}${variant}.${ext}"
+            sha256sum "bundles/${archive}" | awk '{printf "%s  %s\n", $1, $2}' >> "$MANIFEST"
+            echo "  Created bundles/${archive}"
+          }
+
+          # Platform: linux-x64
+          bundle linux-x64 \
+            codewhale-linux-x64 codewhale-tui-linux-x64 tar.gz ""
+
+          # Platform: linux-arm64
+          bundle linux-arm64 \
+            codewhale-linux-arm64 codewhale-tui-linux-arm64 tar.gz ""
+
+          # Platform: linux-riscv64
+          bundle linux-riscv64 \
+            codewhale-linux-riscv64 codewhale-tui-linux-riscv64 tar.gz ""
+
+          # Platform: macos-x64
+          bundle macos-x64 \
+            codewhale-macos-x64 codewhale-tui-macos-x64 tar.gz ""
+
+          # Platform: macos-arm64
+          bundle macos-arm64 \
+            codewhale-macos-arm64 codewhale-tui-macos-arm64 tar.gz ""
+
+          # Platform: windows-x64 (standard + portable)
+          bundle windows-x64 \
+            codewhale-windows-x64.exe codewhale-tui-windows-x64.exe zip ""
+          bundle windows-x64 \
+            codewhale-windows-x64.exe codewhale-tui-windows-x64.exe zip "portable"
+
+          echo ""
+          echo "=== Archive checksums ==="
+          cat "$MANIFEST"
+
+      - name: Upload bundle artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: codewhale-bundles
+          path: bundles/*
+          if-no-files-found: error
+
   docker:
     needs: [build, resolve]
     if: ${{ !cancelled() && needs.build.result == 'success' }}
@@ -292,8 +432,8 @@ jobs:
           cache-to: type=gha,mode=max
 
   release:
-    needs: [build, docker, resolve]
-    if: ${{ !cancelled() && needs.build.result == 'success' && needs.docker.result == 'success' }}
+    needs: [build, bundle, docker, resolve]
+    if: ${{ !cancelled() && needs.build.result == 'success' && needs.bundle.result == 'success' && needs.docker.result == 'success' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -365,35 +505,53 @@ jobs:
 
             Both crates are required — `codewhale-cli` produces the `codewhale` dispatcher and `codewhale-tui` produces the interactive runtime that the dispatcher delegates to. Installing only one binary will fail at runtime with a `MISSING_COMPANION_BINARY` error.
 
-            ### Manual download
+            ### Manual download — platform archives (recommended)
 
-            **Both** binaries below must be downloaded for your platform and dropped into the same directory (e.g. `~/.local/bin/`):
+            Each archive below contains **both** the `codewhale` dispatcher and `codewhale-tui` runtime, plus an install script:
 
-            | Platform | Dispatcher | TUI runtime |
+            | Platform | Archive | Install script |
             |---|---|---|
-            | Linux x64 | `codewhale-linux-x64` | `codewhale-tui-linux-x64` |
-            | Linux ARM64 | `codewhale-linux-arm64` | `codewhale-tui-linux-arm64` |
-            | macOS x64 | `codewhale-macos-x64` | `codewhale-tui-macos-x64` |
-            | macOS ARM | `codewhale-macos-arm64` | `codewhale-tui-macos-arm64` |
-            | Windows x64 | `codewhale-windows-x64.exe` | `codewhale-tui-windows-x64.exe` |
+            | Linux x64 | `codewhale-linux-x64.tar.gz` | `install.sh` |
+            | Linux ARM64 | `codewhale-linux-arm64.tar.gz` | `install.sh` |
+            | Linux RISC-V | `codewhale-linux-riscv64.tar.gz` | `install.sh` |
+            | macOS x64 | `codewhale-macos-x64.tar.gz` | `install.sh` |
+            | macOS ARM | `codewhale-macos-arm64.tar.gz` | `install.sh` |
+            | Windows x64 | `codewhale-windows-x64.zip` | `install.bat` |
+            | Windows x64 (portable) | `codewhale-windows-x64-portable.zip` | — |
 
-            Then `chmod +x` both (Unix) and run `./codewhale`.
+            **Unix (Linux / macOS):**
+            ```bash
+            tar xzf codewhale-<platform>.tar.gz
+            cd codewhale-<platform>
+            ./install.sh
+            ```
 
-            Legacy `deepseek-*` and `deepseek-tui-*` assets are also attached for one release cycle so that existing `deepseek update` invocations on v0.8.40 keep working; they install the deprecation shims, which forward to the canonical binaries.
+            **Windows:**
+            - Extract `codewhale-windows-x64.zip`
+            - Run `install.bat` (copies to `%USERPROFILE%\bin`)
+            - Add `%USERPROFILE%\bin` to your PATH
+
+            The **portable** Windows archive skips the install script — extract and run from any directory.
+
+            Individual binaries are also attached below for scripting and the npm wrapper. Legacy `deepseek-*` and `deepseek-tui-*` assets ship for one release cycle so that existing `deepseek update` invocations on v0.8.40 keep working; they install the deprecation shims, which forward to the canonical binaries.
 
             ### Verify (recommended)
 
-            Download `codewhale-artifacts-sha256.txt` from this Release and verify:
+            Download the checksum manifests from this Release and verify:
 
             ```bash
-            # Linux
+            # Linux — archive bundles
+            sha256sum -c codewhale-bundles-sha256.txt
+
+            # Linux — individual binaries
             sha256sum -c codewhale-artifacts-sha256.txt
 
             # macOS
+            shasum -a 256 -c codewhale-bundles-sha256.txt
             shasum -a 256 -c codewhale-artifacts-sha256.txt
             ```
 
-            The legacy `deepseek-artifacts-sha256.txt` is also attached for backward compatibility and contains the same hashes.
+            The legacy `deepseek-artifacts-sha256.txt` is also attached for backward compatibility and contains the same hashes as the canonical manifest.
 
             ## Changelog
 
diff --git a/.gitignore b/.gitignore
index 0668130d..879e0d91 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,6 +39,7 @@ dist/
 # Generated
 outputs/
 tmp/
+backup/
 
 # Reference papers / large research blobs (keep locally if needed, don't ship)
 docs/DeepSeek_V4.pdf
@@ -48,6 +49,7 @@ docs/*.pdf
 
 # Local dev scripts and temp files
 *.sh
+*.cmd
 !scripts/**
 !.github/scripts/**
 test.txt
@@ -100,6 +102,8 @@ apps/
 # Maintainer-local SWE-bench scratch (instance workspaces, venvs, predictions,
 # Docker harness logs). Never published.
 .swebench/
+deep-swe/
+all_preds.jsonl
 
 # Agent handoffs and version-specific setup plans are working-state notes, not
 # public docs. Keep durable setup guidance in docs/runbooks instead.
@@ -111,3 +115,4 @@ docs/*_PLAN.md
 # direnv
 .envrc
 .direnv
+scripts/run_deep_swe.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6fda0e4..924e4f2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,218 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Composer text selection with copy/cut.** Mouse drag and Shift+Arrow
+  selection in the composer input box, with Ctrl+C copy and Ctrl+X cut
+  support. Home, End, Ctrl+A, and Ctrl+E now clear the selection (#2228).
+- **Copy transcript without visual-wrap newlines.** Transcript copy now
+  strips visual-wrap column line breaks from paragraphs, producing clean
+  text for pasting into editors or prompts (#1906).
+- **Configurable base URL in /config view.** The `/config` panel now
+  displays the effective DeepSeek base URL (#1967).
+- **CNB mirror support for China-friendly downloads.** Added
+  `CODEWHALE_RELEASE_BASE_URL` and `CODEWHALE_USE_CNB_MIRROR` to
+  both npm install scripts and Rust self-updater (#2222).
+- **[✓] completion markers.** Checklist, plan, and tool completion
+  markers now render as `[✓]` instead of `[x]` (#1935).
+
+### Changed
+
+- **Project context loading now logs the source file.** (#2227)
+- **macOS onboarding and empty-state layout pinned to top** instead
+  of vertically centered (#1837).
+- **State-root migration continues.** Migrated 15+ storage paths to
+  prefer `~/.codewhale` with `~/.deepseek` fallback (#2231).
+- **READMEs updated for the CodeWhale rename.** All three READMEs now
+  reference canonical `~/.codewhale` paths.
+
+### Fixed
+
+- **Deadlock when spawning multiple concurrent sub-agents.** Replaced
+  `RwLock`-based serialisation with a `Semaphore(1)` (#1856).
+- **Steered/queued messages now render in correct transcript order.**
+  `steer_user_message` now flushes the active cell before inserting (#2225).
+- **Session save test updated for managed sessions directory.** (#2223).
+- **Loop guard reports Failed on halt.** Turn outcome correctly reports
+  `Failed` instead of `Completed` when the loop guard trips (#1859).
+- **DEEPSEEK_YOLO env honoured on startup.** The `--yolo` flag is now
+  correctly merged with the `DEEPSEEK_YOLO` environment variable (#1870).
+
+### Community
+
+Thanks to contributors whose PRs landed in this release:
+**@Fire-dtx** (#1856),
+**@imkingjh999** (#2228),
+**@harvey2011888** (#1859),
+**@victorcheng2333** (#1870),
+**@IIzzaya** (#1935),
+**@PurplePulse** (#1837),
+**@cyq1017** (#1967),
+**@knqiufan** (#1906).
+
+## [0.8.46] - 2026-05-26
+
+### Added
+
+- **`CODEWHALE_*` env aliases.** `CODEWHALE_PROVIDER`, `CODEWHALE_MODEL`,
+  and `CODEWHALE_BASE_URL` are public product-scoped aliases that take
+  precedence over the legacy `DEEPSEEK_*` forms. The `DEEPSEEK_*` names
+  remain accepted for back-compat.
+- **Platform archive bundles.** Release artifacts now ship as per-platform
+  archives (`tar.gz` for Linux/macOS, `.zip` for Windows) containing both
+  `codewhale` and `codewhale-tui` binaries plus an install script. No more
+  downloading two loose files and guessing which ones to pick (#2193).
+- **Windows portable archive.** `codewhale-windows-x64-portable.zip` ships
+  the two binaries without an install script for USB-stick distribution
+  (#2193).
+- **Web install download tile.** The website install page now shows a
+  platform-aware download tile with arch detection, SHA256 checksum
+  display, and China mirror links, instead of burying the download behind
+  the Cargo instructions (#2192).
+- **Whale dark palette refresh.** Better contrast and layer separation
+  across the TUI color scheme (#2197).
+- **Auto-collapse finished sub-agents.** Completed sub-agent sessions now
+  collapse automatically in the sidebar, reducing noise during long
+  sessions (#2195).
+- **Shell-running status chip.** A `⏳ shell running` chip appears in the
+  TUI footer while background shell tasks are active (#2194).
+- **Sandbox process hardening (Linux).** `PR_SET_DUMPABLE=0`,
+  `NO_NEW_PRIVS`, and `RLIMIT_CORE=0` are applied at shell startup to
+  harden child processes against inspection and privilege escalation
+  (#2183).
+- **CONTRIBUTING.md cross-links.** Issue and PR templates are now
+  cross-linked from CONTRIBUTING.md to improve contributor onboarding
+  (#2203).
+
+### Changed
+
+- **DeepSeek-first focus.** v0.8.46 refocuses on delivering the
+  highest-quality experience on DeepSeek first. Additional first-class
+  provider paths are planned for v0.9.0 after the core DeepSeek workflow
+  is solid.
+
+### Fixed
+
+- **Model name casing preserved.** `normalize_model_name_for_provider` no
+  longer lowercases user-set model names such as `DeepSeek-V4-Flash`,
+  preventing API lookup failures on case-sensitive backends (#2109).
+- **Esc in model picker applies selection.** Dismissing the model picker
+  with Esc now applies the last-highlighted choice instead of reverting
+  (#2196).
+- **Web install downloads both binaries.** The `install-binary.tsx`
+  snippet now fetches both `codewhale` and `codewhale-tui`, fixing the
+  `MISSING_COMPANION_BINARY` trap on fresh npm installs (#2191).
+- **`grep_files` skips large directories.** The pure-Rust search tool
+  now skips known-large directories (`.git`, `node_modules`, `target`)
+  before walking, preventing hangs on deep or slow filesystems.
+- **Version-update hint uses semver.** The update notification in the
+  footer now compares versions semantically instead of lexicographically,
+  so `0.8.10 > 0.8.9` is recognized correctly.
+- **CVE-2026-8723 in feishu-bridge.** Bumped `qs` to `>=6.15.2` in the
+  Feishu bridge integration (#2198).
+
+### Community
+
+Thanks to new contributors whose PRs landed in this release:
+**@donglovejava** (#2154, #2163, #2166, #2167, #2168),
+**@encyc** (#2152),
+**@saieswar237** (#2178),
+**@sximelon** (#2174),
+**@nanookclaw** (#2135),
+**@Sskift** (#2119),
+**@xin1104** (#2105),
+**@mrluanma** (#2059),
+**@Lellansin** (#2055),
+**@zhuangbiaowei** (#2145),
+**@aboimpinto** (#1872),
+and continuing contributors **@reidliu41**, **@cyq1017**, **@idling11**,
+**@h3c-hexin**, **@wdw8276**, **@zlh124**, and **@jeoor**.
+
+## [0.8.45] - 2026-05-25
+
+### Added
+
+- **RLM session objects.** `rlm_open` can now load `session://` refs,
+  exposing the active prompt, history, and session data as symbolic objects
+  inside RLM REPLs (#2047).
+- **Command palette voice input.** The command palette can launch a configured
+  speech-to-text helper and show footer status while transcription runs
+  (#2047).
+- **Moonshot/Kimi provider.** Moonshot/Kimi is now a first-class provider,
+  including API-key auth, model completion, CLI auth, secret-store
+  integration, and optional Kimi CLI credential reuse.
+- **Deterministic whale-species sub-agent names.** Sub-agents now get stable,
+  human-readable whale-species nicknames (e.g. "Beluga", "Orca") while
+  preserving the raw agent ID in the popup (#2035, #2016).
+- **`/balance` command scaffold.** Registered the `/balance` slash command
+  as a placeholder for future provider billing queries (#2035, #2019).
+- **Readable `/restore` snapshot labels.** Snapshot labels now include the
+  originating user prompt so restore listings are easier to identify. Thanks
+  @idling11 (#2111).
+- **Sidebar hover tooltips.** Truncated Work and Tasks sidebar lines now expose
+  their full text on hover. Thanks @idling11 (#2110).
+
+### Changed
+
+- **AGENTS.md is now maintainer-local.** The project instructions file no
+  longer ships as a tracked repo file; it lives in maintainer-local ignored
+  state (#2047).
+
+### Fixed
+
+- **Sub-agent completion handoff compatibility.** Completion handoffs now use a
+  chat-template-safe role and emit before terminal updates, fixing strict
+  OpenAI-compatible/self-hosted backends and preserving transcript ordering.
+  Thanks @h3c-hexin and @cyq1017 (#2057, #2120).
+- **Self-hosted context budgeting.** Sub-500K self-hosted model windows now keep
+  a usable input budget instead of disabling preflight compaction after output
+  reservation underflow. Thanks @h3c-hexin (#2060).
+- **Goal prompts start actionable.** Goal-start prompts now open in an
+  actionable state instead of requiring an extra nudge. Thanks @cyq1017
+  (#2097).
+- **Composer session title display.** The composer chrome shows the current
+  session title again and avoids grayscale luma overflow in debug builds.
+  Thanks @wdw8276 (#2108).
+- **Approval prompts use a one-step confirmation flow.** Enter now commits the
+  selected approval option directly, destructive warnings remain visible, and
+  abort cancels the active turn instead of only denying the current tool call.
+  Thanks @reidliu41 (#2143).
+- **Model picker selection survives Esc.** Dismissing the model picker with Esc
+  no longer loses the highlighted selection. Thanks @reidliu41 (#2056).
+- **Moonshot/Kimi sessions launch from the dispatcher.** The `codewhale`
+  wrapper now includes Moonshot/Kimi in the TUI provider allowlist, so
+  `codewhale --provider moonshot --model kimi-k2.6` reaches the TUI instead of
+  stopping after config resolution.
+- **Slash recovery no longer restores command tails in the composer.**
+  Resuming a session or recovering from a crash no longer leaves stale
+  slash-command text (e.g. `/sessions`) in the composer input (#2047, #2032).
+- **Remembered tool approvals now update the live active turn.**
+  When the "remember" checkbox is set on an approval dialog, the active
+  turn's auto-approve flag flips immediately instead of waiting for the
+  next turn. Thanks @gaord (#2047, #2041).
+- **YAML block scalars in SKILL.md frontmatter.** Multi-line descriptions
+  using `>` or `|` indicators are now parsed correctly — folded block
+  scalars join non-empty lines with spaces, literal scalars preserve
+  newlines, and all three chomping modes (strip/clip/keep) are supported.
+  Thanks @zlh124 (#1908, #1907).
+- **User messages highlighted in the transcript.** User-authored messages
+  now render with a full-row background in the live TUI transcript, making
+  it easier to scan prior turns. Assistant and system messages are
+  unaffected. Thanks @reidliu41 (#1995, #1672).
+- **Cancellable `list_dir` and `file_search`.** Long directory walks and
+  file searches now respond to user cancel/stop requests with a 30-second
+  fallback timeout, preventing the TUI from hanging on deep or slow
+  filesystems (#2035).
+
+### Community
+
+- **README contributor acknowledgements resynced.** The Thanks list now
+  includes the latest contributor rows for @donglovejava, @encyc,
+  @saieswar237, @sximelon, @nanookclaw, @Sskift, @xin1104, @mrluanma,
+  @Lellansin, and @zhuangbiaowei, while preserving the existing @jeoor
+  acknowledgement in the consolidated list.
+
 ## [0.8.44] - 2026-05-24
 
 ### Added
@@ -4806,7 +5018,9 @@ Welcome — and thank you.
 - Hooks system and config profiles
 - Example skills and launch assets
 
-[Unreleased]: https://github.com/Hmbown/CodeWhale/compare/v0.8.44...HEAD
+[Unreleased]: https://github.com/Hmbown/CodeWhale/compare/v0.8.46...HEAD
+[0.8.46]: https://github.com/Hmbown/CodeWhale/compare/v0.8.45...v0.8.46
+[0.8.45]: https://github.com/Hmbown/CodeWhale/compare/v0.8.44...v0.8.45
 [0.8.44]: https://github.com/Hmbown/CodeWhale/compare/v0.8.43...v0.8.44
 [0.8.43]: https://github.com/Hmbown/CodeWhale/compare/v0.8.42...v0.8.43
 [0.8.42]: https://github.com/Hmbown/CodeWhale/compare/v0.8.41...v0.8.42
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 759b6d44..1cbc15b0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -184,6 +184,9 @@ these crates, including the bottom-up build order.
 
 ## Pull Request Guidelines
 
+- Use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md) when opening
+  a PR — it includes the Summary, Testing, and Checklist sections reviewers
+  expect
 - Keep PRs focused on a single change
 - Update documentation if needed
 - Add tests for new functionality
@@ -217,7 +220,14 @@ cargo check
 
 ## Reporting Issues
 
-When reporting issues, please include:
+When reporting issues, please use one of the issue templates:
+
+- [Bug report](.github/ISSUE_TEMPLATE/bug_report.md) — for reproducible problems
+  or regressions
+- [Feature request](.github/ISSUE_TEMPLATE/feature_request.md) — for ideas and
+  improvements
+
+Issue reports should include:
 
 - Operating system and version
 - Rust version (`rustc --version`)
@@ -226,9 +236,17 @@ When reporting issues, please include:
 - Expected vs actual behavior
 - Relevant error messages or logs
 
+## Security
+
+If you discover a security vulnerability, please do **not** open a public issue.
+See [SECURITY.md](SECURITY.md) for the responsible disclosure process and
+contact information.
+
 ## Code of Conduct
 
-Be respectful and inclusive. We welcome contributors of all backgrounds and experience levels.
+Be respectful and inclusive. We welcome contributors of all backgrounds and
+experience levels. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for the full
+code of conduct.
 
 ## License
 
diff --git a/Cargo.lock b/Cargo.lock
index 2d5bd8e1..fcd2407b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -803,7 +803,7 @@ checksum = "e9b18233253483ce2f65329a24072ec414db782531bdbb7d0bbc4bd2ce6b7e21"
 
 [[package]]
 name = "codewhale-agent"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "codewhale-config",
  "serde",
@@ -811,7 +811,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-app-server"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "axum",
@@ -827,13 +827,16 @@ dependencies = [
  "codewhale-tools",
  "serde",
  "serde_json",
+ "tempfile",
  "tokio",
+ "tower",
  "tower-http",
+ "uuid",
 ]
 
 [[package]]
 name = "codewhale-cli"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "chrono",
@@ -844,10 +847,12 @@ dependencies = [
  "codewhale-config",
  "codewhale-execpolicy",
  "codewhale-mcp",
+ "codewhale-release",
  "codewhale-secrets",
  "codewhale-state",
  "dirs",
  "reqwest",
+ "semver",
  "serde",
  "serde_json",
  "sha2 0.10.9",
@@ -858,19 +863,20 @@ dependencies = [
 
 [[package]]
 name = "codewhale-config"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "codewhale-secrets",
  "dirs",
  "serde",
+ "serde_json",
  "toml 0.9.11+spec-1.1.0",
  "tracing",
 ]
 
 [[package]]
 name = "codewhale-core"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "chrono",
@@ -888,7 +894,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-execpolicy"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "codewhale-protocol",
@@ -897,7 +903,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-hooks"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -911,7 +917,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-mcp"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "serde",
@@ -920,15 +926,26 @@ dependencies = [
 
 [[package]]
 name = "codewhale-protocol"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "serde",
  "serde_json",
 ]
 
+[[package]]
+name = "codewhale-release"
+version = "0.8.46"
+dependencies = [
+ "anyhow",
+ "reqwest",
+ "semver",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "codewhale-secrets"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "dirs",
  "keyring",
@@ -941,7 +958,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-state"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "chrono",
@@ -953,7 +970,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-tools"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -966,7 +983,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-tui"
-version = "0.8.44"
+version = "0.8.46"
 dependencies = [
  "anyhow",
  "arboard",
@@ -978,6 +995,7 @@ dependencies = [
  "clap",
  "clap_complete",
  "codewhale-config",
+ "codewhale-release",
  "codewhale-secrets",
  "codewhale-tools",
  "colored",
@@ -1032,7 +1050,7 @@ dependencies = [
 
 [[package]]
 name = "codewhale-tui-core"
-version = "0.8.44"
+version = "0.8.46"
 
 [[package]]
 name = "colorchoice"
@@ -2560,15 +2578,6 @@ dependencies = [
  "rustversion",
 ]
 
-[[package]]
-name = "ioctl-rs"
-version = "0.1.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f7970510895cee30b3e9128319f2cefd4bde883a39f38baa279567ba3a7eb97d"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "ipnet"
 version = "2.11.0"
@@ -3094,20 +3103,6 @@ dependencies = [
  "smallvec",
 ]
 
-[[package]]
-name = "nix"
-version = "0.25.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f346ff70e7dbfd675fe90590b92d59ef2de15a8779ae305ebcbfd3f0caf59be4"
-dependencies = [
- "autocfg",
- "bitflags 1.3.2",
- "cfg-if",
- "libc",
- "memoffset 0.6.5",
- "pin-utils",
-]
-
 [[package]]
 name = "nix"
 version = "0.28.0"
@@ -3620,9 +3615,9 @@ checksum = "f89776e4d69bb58bc6993e99ffa1d11f228b839984854c7daeb5d37f87cbe950"
 
 [[package]]
 name = "portable-pty"
-version = "0.8.1"
+version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "806ee80c2a03dbe1a9fb9534f8d19e4c0546b790cde8fd1fea9d6390644cb0be"
+checksum = "b4a596a2b3d2752d94f51fac2d4a96737b8705dddd311a32b9af47211f08671e"
 dependencies = [
  "anyhow",
  "bitflags 1.3.2",
@@ -3631,8 +3626,8 @@ dependencies = [
  "lazy_static",
  "libc",
  "log",
- "nix 0.25.1",
- "serial",
+ "nix 0.28.0",
+ "serial2",
  "shared_library",
  "shell-words",
  "winapi",
@@ -4090,6 +4085,7 @@ dependencies = [
  "rustls-platform-verifier",
  "serde",
  "serde_json",
+ "serde_urlencoded",
  "sync_wrapper",
  "tokio",
  "tokio-rustls",
@@ -4578,45 +4574,14 @@ dependencies = [
 ]
 
 [[package]]
-name = "serial"
-version = "0.4.0"
+name = "serial2"
+version = "0.2.37"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1237a96570fc377c13baa1b88c7589ab66edced652e43ffb17088f003db3e86"
-dependencies = [
- "serial-core",
- "serial-unix",
- "serial-windows",
-]
-
-[[package]]
-name = "serial-core"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3f46209b345401737ae2125fe5b19a77acce90cd53e1658cda928e4fe9a64581"
+checksum = "9eb6ea5562eeaed6936b8b54e086aa0f88b9e5b1bef45beb038e2519fa1185b1"
 dependencies = [
+ "cfg-if",
  "libc",
-]
-
-[[package]]
-name = "serial-unix"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f03fbca4c9d866e24a459cbca71283f545a37f8e3e002ad8c70593871453cab7"
-dependencies = [
- "ioctl-rs",
- "libc",
- "serial-core",
- "termios 0.2.2",
-]
-
-[[package]]
-name = "serial-windows"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "15c6d3b776267a75d31bbdfd5d36c0ca051251caafc285827052bc53bcdc8162"
-dependencies = [
- "libc",
- "serial-core",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -4960,9 +4925,9 @@ dependencies = [
 
 [[package]]
 name = "tar"
-version = "0.4.45"
+version = "0.4.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22692a6476a21fa75fdfc11d452fda482af402c008cdbaf3476414e122040973"
+checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
 dependencies = [
  "filetime",
  "libc",
@@ -5005,15 +4970,6 @@ dependencies = [
  "phf_codegen",
 ]
 
-[[package]]
-name = "termios"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d5d9cf598a6d7ce700a4e6a9199da127e6819a61e64b68609683cc9a01b5683a"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "termios"
 version = "0.3.3"
@@ -5052,7 +5008,7 @@ dependencies = [
  "signal-hook",
  "siphasher",
  "terminfo",
- "termios 0.3.3",
+ "termios",
  "thiserror 1.0.69",
  "ucd-trie",
  "unicode-segmentation",
diff --git a/Cargo.toml b/Cargo.toml
index cee78462..90b8a172 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,6 +9,7 @@ members = [
     "crates/hooks",
     "crates/mcp",
     "crates/protocol",
+    "crates/release",
     "crates/secrets",
     "crates/state",
     "crates/tools",
@@ -19,7 +20,7 @@ default-members = ["crates/cli", "crates/app-server", "crates/tui"]
 resolver = "2"
 
 [workspace.package]
-version = "0.8.44"
+version = "0.8.46"
 edition = "2024"
 # Rust 1.88 stabilized `let_chains` in `if`/`while` conditions, which the
 # codebase relies on extensively. Cargo enforces this so users on older
@@ -37,10 +38,11 @@ chrono = { version = "0.4.43", features = ["serde"] }
 clap = { version = "4.5.54", features = ["derive"] }
 clap_complete = "4.5"
 dirs = "6.0.0"
-reqwest = { version = "0.13.1", default-features = false, features = ["json", "rustls"] }
+reqwest = { version = "0.13.1", default-features = false, features = ["json", "rustls", "socks"] }
 rusqlite = { version = "0.32.1", features = ["bundled"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.149"
+semver = "1.0.28"
 thiserror = "2.0"
 tokio = { version = "1.49.0", features = ["full"] }
 toml = "0.9.7"
diff --git a/README.ja-JP.md b/README.ja-JP.md
index dc21668d..92bfd0cb 100644
--- a/README.ja-JP.md
+++ b/README.ja-JP.md
@@ -1,45 +1,41 @@
 # 🐳 CodeWhale
 
-> **DeepSeek ファーストで、オープンソースおよびオープンウェイトのコーディングモデルに向けたターミナルネイティブのコーディングエージェントです。DeepSeek V4 の 100 万トークンのコンテキストウィンドウとプレフィックスキャッシュ機能を中心に構築されています。単一のバイナリとして配布され、Node.js や Python のランタイムは不要です。MCP クライアント、サンドボックス、永続的なタスクキューも標準で同梱されています。**
-
-[![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale)
-[![crates.io](https://img.shields.io/crates/v/codewhale-cli?label=crates.io)](https://crates.io/crates/codewhale-cli)
-[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Hmbown)
-[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_AI-_.svg?style=flat&color=0052D9&labelColor=000000&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/Hmbown/CodeWhale)
+> **このターミナルネイティブのコーディングエージェントは、DeepSeek V4 の 100 万トークンのコンテキストウィンドウとプレフィックスキャッシュ機能を中心に構築されています。`codewhale` ディスパッチャーと `codewhale-tui` ランタイムの Rust バイナリペアとして配布され、Node.js や Python のランタイムは不要です。MCP クライアント、サンドボックス、永続的なタスクキューも標準で同梱されています。**
 
 [English README](README.md)
 [简体中文 README](README.zh-CN.md)
+[Tiếng Việt README](README.vi.md)
 
-[インストール](#インストール) · [クイックスタート](#クイックスタート) · [ドキュメント](#ドキュメント) · [コントリビューション](#コントリビューション) · [サポート](#サポート)
 
 ## インストール
 
-`codewhale` は自己完結型の Rust バイナリとして提供されており、**実行に Node.js や Python のランタイムは必要ありません。** すでにマシンにインストールされているものを選んでください。いずれの方法でも同じバイナリが `PATH` に配置されます。
+`codewhale` は自己完結型の Rust リリースバイナリのペアとしてインストールされます。`codewhale` はディスパッチャーで、同じ場所にある `codewhale-tui` ランタイムを起動して対話セッションを実行します。npm、Homebrew、Docker は両方を自動でインストールします。Cargo や手動インストールでは、両方を同じディレクトリ（通常は `PATH` 上のディレクトリ）に置いてください。実行に Node.js や Python のランタイムは不要です。
 
 ```bash
 # 1. npm — すでに Node を使っているなら最も簡単。npm パッケージは
-#    GitHub Releases から対応するビルド済みバイナリをダウンロードする
+#    GitHub Releases から対応するビルド済みバイナリペアをダウンロードする
 #    薄いインストーラーであり、codewhale 本体に Node ランタイム依存を加えるものではありません。
 npm install -g codewhale
 
-# 2. Cargo — Node 不要。
+# 2. Cargo — Node 不要。2 つの crate を両方インストールします。
 cargo install codewhale-cli --locked   # `codewhale` (エントリーポイント)
 cargo install codewhale-tui     --locked   # `codewhale-tui` (TUI バイナリ)
 
 # 3. Homebrew — macOS パッケージマネージャ。
+#    tap/formula 名は旧名のままですが、codewhale と codewhale-tui をインストールします。
 brew tap Hmbown/deepseek-tui
 brew install deepseek-tui
 
-# 4. 直接ダウンロード — Node もツールチェーンも不要。
+# 4. 直接ダウンロード — GitHub Releases のプラットフォームアーカイブ。
 #    https://github.com/Hmbown/CodeWhale/releases
-#    Linux x64/ARM64、macOS x64/ARM64、Windows x64 向けのビルド済みバイナリがあります。
+#    アーカイブには codewhale と codewhale-tui とインストールスクリプトが含まれます。
+#    個別バイナリもスクリプト用に添付されています。手動ではペアを同じ場所に置いてください。
 
 # 5. Docker — ビルド済みリリースイメージ。
 docker volume create codewhale-home
 docker run --rm -it \
   -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-  -v codewhale-home:/home/codewhale/.deepseek \
+  -v codewhale-home:/home/codewhale/.codewhale \
   -v "$PWD:/workspace" \
   -w /workspace \
   ghcr.io/hmbown/codewhale:latest
@@ -57,40 +53,59 @@ cargo install codewhale-cli --locked --force
 cargo install codewhale-tui     --locked --force
 ```
 
+> codewhale update は --proxy をサポートしており、プロキシ経由で更新できます
+> 例: codewhale update --proxy https://localhost:7897
+
+[![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale)
+[![crates.io](https://img.shields.io/crates/v/codewhale-cli?label=crates.io)](https://crates.io/crates/codewhale-cli)
+[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_AI-_.svg?style=flat&color=0052D9&labelColor=000000&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/Hmbown/CodeWhale)
+
+<a href="https://www.buymeacoffee.com/hmbown" target="_blank"><img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-5F7FFF?style=for-the-badge&logo=buymeacoffee&logoColor=white" alt="Buy me a coffee" /></a>
+
 ![codewhale スクリーンショット](assets/screenshot.png)
 
 ---
 
 ## codewhale とは？
 
-codewhale は、ターミナル内で完結するコーディングエージェントです。DeepSeek のフロンティアモデルがあなたのワークスペースに直接アクセスできるようにし、ファイルの読み取り・編集、シェルコマンドの実行、Web 検索、Git 管理、サブエージェントの統制などを、すべて高速でキーボード駆動の TUI を通じて行えます。
+モデルは質問に答えます。エージェントはタスクを完了します。その差がハーネス——モデルが迷走しないようにするルール、証拠、フィードバックのシステムです。
 
-**DeepSeek V4 向けに構築** (`deepseek-v4-pro` / `deepseek-v4-flash`)。100 万トークンのコンテキストウィンドウとネイティブの thinking-mode（思考連鎖）ストリーミングをサポートします。
+CodeWhale はそのハーネスであり、DeepSeek V4 を中心に構築され、3つの原則に導かれています：
 
-### 主な機能
+| 原則 | 仕組み |
+|---|---|
+| **信頼から始める** | 毎ターン「A」で始まる——確実性より可能性、便利さより丁寧さ |
+| **明確な管轄権** | 9階層の権威を持つ成文憲法。ユーザーの意図が古い指示より優先。検証が自信より優先。 |
+| **再帰的改善** | V4 がハーネスの一部を書いた。ハーネスが改善されると V4 はより効果的になり、さらにハーネスを改善する。毎ターンがより強くなる。 |
 
-- **モデル自動ルーティング** — `--model auto` / `/model auto` がターンごとにモデルと推論強度を選択
-- **Fin の高速経路** — thinking off の低コストな `deepseek-v4-flash` がルーティング、RLM 子呼び出し、要約、調整作業を担当
-- **ネイティブ RLM** (`rlm_open`/`rlm_eval`) — 永続 REPL セッションでバッチ解析を行い、`peek`、`search`、`chunk`、`sub_query_batch` などの補助関数を利用
-- **Thinking-mode ストリーミング** — モデルがタスクに取り組む様子をリアルタイムで観察し、思考連鎖の展開を追える
-- **完全なツールスイート** — ファイル操作、シェル実行、Git、Web 検索／ブラウズ、apply-patch、サブエージェント、MCP サーバー
-- **100 万トークンコンテキスト** — コンテキスト追跡、手動または設定ベースのコンパクション、プレフィックスキャッシュのテレメトリ
-- **3 つのモード** — Plan（読み取り専用の探索）、Agent（承認ありのインタラクティブ）、YOLO（自動承認）
-- **推論努力ティア** — `Shift + Tab` で `off → high → max` を切り替え
-- **セッション保存／再開** — 長時間実行のセッションをチェックポイント化して再開可能
-- **ワークスペースのロールバック** — リポジトリの `.git` には触れずに、サイド Git によるターン前後のスナップショットを `/restore` と `revert_turn` で扱える
-- **永続的タスクキュー** — 再起動を超えて生き残るバックグラウンドタスク。スケジュール自動化や長時間レビューなどに
-- **HTTP/SSE ランタイム API** — `codewhale serve --http` でヘッドレスエージェントワークフローを実現
-- **MCP プロトコル** — Model Context Protocol サーバーに接続して拡張ツールを利用可能。詳細は [docs/MCP.md](docs/MCP.md) を参照
-- **LSP 診断** — rust-analyzer、pyright、typescript-language-server、gopls、clangd により、編集ごとにエラー／警告をインライン表示
-- **ユーザーメモリ** — クロスセッションの嗜好をシステムプロンプトに注入できる、オプションの永続メモファイル
-- **ローカライズ済み UI** — `en`、`ja`、`zh-Hans`、`pt-BR` を自動検出
-- **ライブコスト追跡** — ターンごと／セッションごとのトークン使用量とコスト見積もり、キャッシュヒット／ミスの内訳
-- **スキルシステム** — GitHub から取得できる命令パック。初回起動時に `skill-creator`、`mcp-builder`、`documents`、`presentations`、`spreadsheets`、`pdf`、`feishu` などのスターターセットを同梱
+オープンソース、ターミナルネイティブ、`codewhale` / `codewhale-tui` の Rust バイナリペアとして提供されています。
+
+## ハーネスの仕組み
+
+エージェントモデルは大規模な相反する情報を扱います：ユーザーの意図、プロジェクトルール、システムデフォルト、ツール出力、古いメモリが単一ターンで権威を競い合います。LLM が裁判官として機能するには管轄権が必要です——衝突したとき、どの情報源が勝つのか？
+
+CodeWhale は**憲法**（`prompts/base.md`）でこれに答えます。これは形式化された法の階層です——第七条は憲法自体の条項から前セッションのハンドオフまで、9 つの情報源をランク付けします。ユーザーの現在のメッセージは古いプロジェクト指示より上。ライブのツール出力は仮定より上。検証は自信より上。モデルは毎ターン明確な権威チェーンを継承し、どの指示に従うべきか推測する必要がありません。
+
+7 つの条項が階層の上にあり、モデルのアイデンティティ、義務、エージェンシーを定義します：検証義務（第5条——すべての行動は証拠を残し、信念で成功を宣言しない）、協調の遺産（第6条——次の知性のためにワークスペースを可読に保つ）、真実優先条項（第2条——下位のルールで上書きできない）。
+
+DeepSeek V4 のプレフィックスキャッシュがこれを実用的にします。憲法は長く詳細ですが、一度キャッシュされるとコールドリードの約 100 分の 1 のコストになります。モデルはそれを再帰的に参照し——RLM セッションを通じて覗き、スキャンし、クエリし——単一の暗記パスに頼るのではなく、必要に応じて情報を再訪します。それは閉じた本のテストよりも、開いた本のテストのように機能します。
+
+権威構造が明示的であるため、失敗は隠されません。非ゼロの終了コード、ターン間に届く rust-analyzer からの型エラー、サンドボックス拒否——これらは修正ベクトルとしてフィードバックされます。モデルは自身のドリフトを使って自己修正します。
+
+3 つのモードが行動空間を制御します。Plan は読み取り専用。Agent は破壊的操作を承認ゲートの背後に置きます。YOLO は信頼済みワークスペースで自動承認します。macOS Seatbelt はアクティブなサンドボックス；Linux Landlock は検出されるが未適用；Windows サンドボックスは未公開。
+
+Fin——thinking off の安価な Flash 呼び出し——がターンごとにモデル自動ルーティングを処理します。`--model auto` がデフォルトです。
+
+毎ターン side-git スナップショットをリポジトリの `.git` 外に記録。`/restore` と `revert_turn` がワークスペースを即座にロールバックします。
+
+サブエージェントは並行実行（最大 20）。`agent_open` は即座に戻り；結果は完了センチネルとしてインラインで到着し、サマリー付き。完全なトランスクリプトは `agent_eval` を通じて境界付きハンドルに保持されます。[docs/SUBAGENTS.md](docs/SUBAGENTS.md) を参照。
+
+その他の機能面：編集ごとの LSP 診断（rust-analyzer、pyright、typescript-language-server、gopls、clangd）、バッチ分析用 RLM セッション、MCP プロトコル、HTTP/SSE ランタイム API、永続タスクキュー、Zed 向け ACP アダプター、SWE-bench エクスポート、キャッシュヒット/ミス内訳付きライブコスト追跡。
 
 ---
 
-## 仕組み
+## ハーネス
 
 `codewhale`（ディスパッチャー CLI）→ `codewhale-tui`（コンパニオンバイナリ）→ ratatui インターフェース ↔ 非同期エンジン ↔ OpenAI 互換のストリーミングクライアント。ツール呼び出しは型付きレジストリ（シェル、ファイル操作、Git、Web、サブエージェント、MCP、RLM）を経由してルーティングされ、結果はトランスクリプトへとストリーム返送されます。エンジンはセッション状態、ターン管理、永続タスクキューを管理し、LSP サブシステムは編集後の診断を次の推論ステップ前にモデルのコンテキストへ供給します。
 
@@ -106,14 +121,14 @@ codewhale --version
 codewhale --model auto
 ```
 
-ビルド済みバイナリは **Linux x64**、**Linux ARM64**（v0.8.8 以降）、**macOS x64**、**macOS ARM64**、**Windows x64** 向けに公開されています。その他のターゲット（musl、riscv64、FreeBSD など）は [ソースからのインストール](#install-from-source) または [docs/INSTALL.md](docs/INSTALL.md) を参照してください。
+ビルド済みバイナリペアとプラットフォームアーカイブは **Linux x64**、**Linux ARM64**（v0.8.8 以降）、**macOS x64**、**macOS ARM64**、**Windows x64** 向けに公開されています。その他のターゲット（musl、riscv64、FreeBSD など）は [ソースからのインストール](#install-from-source) または [docs/INSTALL.md](docs/INSTALL.md) を参照してください。
 
-初回起動時に [DeepSeek API キー](https://platform.deepseek.com/api_keys) の入力を求められます。キーは `~/.deepseek/config.toml` に保存されるため、OS のクレデンシャルプロンプトなしに任意のディレクトリから利用できます。
+初回起動時に [DeepSeek API キー](https://platform.deepseek.com/api_keys) の入力を求められます。キーは `~/.codewhale/config.toml`（旧 `~/.deepseek/config.toml` も互換性維持）に保存されるため、OS のクレデンシャルプロンプトなしに任意のディレクトリから利用できます。
 
 事前に設定することもできます:
 
 ```bash
-codewhale auth set --provider deepseek   # ~/.deepseek/config.toml に保存
+codewhale auth set --provider deepseek   # ~/.codewhale/config.toml に保存
 
 export DEEPSEEK_API_KEY="YOUR_KEY"      # 環境変数による代替方法。非対話シェルでは ~/.zshenv を使用
 codewhale
@@ -152,10 +167,15 @@ codewhale --version
 
 ### Windows（Scoop）
 
-[Scoop](https://scoop.sh) は Windows のパッケージマネージャです。インストール後、次を実行してください:
+[Scoop](https://scoop.sh) は Windows のパッケージマネージャです。`codewhale`
+パッケージは Scoop main bucket にありますが、manifest は GitHub/npm/Cargo
+リリースより遅れることがあります。先に更新し、インストール後に
+`codewhale --version` で確認してください:
 
 ```bash
-scoop install deepseek-tui
+scoop update
+scoop install codewhale
+codewhale --version
 ```
 
 
@@ -199,6 +219,10 @@ codewhale --provider wanjie-ark --model deepseek-reasoner
 codewhale auth set --provider openrouter --api-key "YOUR_OPENROUTER_API_KEY"
 codewhale --provider openrouter --model deepseek/deepseek-v4-pro
 
+# Xiaomi MiMo
+codewhale auth set --provider xiaomi-mimo --api-key "YOUR_XIAOMI_MIMO_API_KEY"
+codewhale --provider xiaomi-mimo --model mimo-v2.5-pro
+
 # Novita
 codewhale auth set --provider novita --api-key "YOUR_NOVITA_API_KEY"
 codewhale --provider novita --model deepseek/deepseek-v4-pro
@@ -237,10 +261,10 @@ TUI 内では `/provider` でプロバイダーピッカー、`/model` でロー
 ```bash
 codewhale                                         # インタラクティブ TUI
 codewhale "explain this function"                 # ワンショットプロンプト
-codewhale exec --auto --output-format stream-json "fix this bug"  # ツール自動承認付きの agentic exec
+codewhale exec --auto --output-format stream-json "fix this bug"  # NDJSON バックエンドストリーム
 codewhale exec --resume <SESSION_ID> "follow up"  # 非対話セッションを継続
 codewhale --model deepseek-v4-flash "summarize"   # モデルの上書き
-codewhale --model auto "fix this bug"             # モデルと推論強度を自動ルーティング
+codewhale --model auto "fix this bug"             # モデルと推論強度を自動選択
 codewhale --yolo                                  # ツールを自動承認
 codewhale auth set --provider deepseek            # API キーの保存
 codewhale doctor                                  # セットアップと接続性のチェック
@@ -289,16 +313,11 @@ codewhale update                                  # バイナリ更新の確認
 | **Agent** 🤖 | デフォルトのインタラクティブモード — 承認ゲート付きのマルチステップなツール利用。モデルは `checklist_write` で作業を概説 |
 | **YOLO** ⚡ | 信頼できるワークスペースですべてのツールを自動承認。可視性のための計画とチェックリストは引き続き維持 |
 
-モードとモデル自動ルーティングは別物です。`Tab` は Plan / Agent / YOLO
-を切り替え、`/model auto` はモデルと thinking レベルを選びます。`/goal`
-は現時点ではセッション目標と token 予算の追跡であり、将来の Goal
-ワークサーフェスは `--model auto` とは別に扱います。
-
 ---
 
 ## 設定
 
-ユーザー設定: `~/.deepseek/config.toml`。プロジェクトオーバーレイ: `<workspace>/.deepseek/config.toml`（拒否される項目: `api_key`、`base_url`、`provider`、`mcp_config_path`）。すべてのオプションは [config.example.toml](config.example.toml) にあります。
+ユーザー設定: `~/.codewhale/config.toml`（旧 `~/.deepseek/config.toml` も互換性維持）。プロジェクトオーバーレイ: `<workspace>/.codewhale/config.toml`（旧 `<workspace>/.deepseek/config.toml`）（拒否される項目: `api_key`、`base_url`、`provider`、`mcp_config_path`）。すべてのオプションは [config.example.toml](config.example.toml) にあります。
 
 主な環境変数:
 
@@ -309,15 +328,16 @@ codewhale update                                  # バイナリ更新の確認
 | `DEEPSEEK_HTTP_HEADERS` | 任意のモデルリクエストヘッダー |
 | `DEEPSEEK_MODEL` | デフォルトモデル |
 | `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` | ストリームのアイドルタイムアウト秒数 |
-| `DEEPSEEK_PROVIDER` | `codewhale`（デフォルト）、`nvidia-nim`、`openai`、`atlascloud`、`wanjie-ark`、`openrouter`、`novita`、`fireworks`、`sglang`、`vllm`、`ollama` |
+| `DEEPSEEK_PROVIDER` | `codewhale`（デフォルト）、`nvidia-nim`、`openai`、`atlascloud`、`wanjie-ark`、`openrouter`、`xiaomi-mimo`、`novita`、`fireworks`、`sglang`、`vllm`、`ollama` |
 | `DEEPSEEK_PROFILE` | 設定プロファイル名 |
 | `DEEPSEEK_MEMORY` | `on` に設定するとユーザーメモリを有効化 |
 | `DEEPSEEK_ALLOW_INSECURE_HTTP=1` | 信頼できるネットワークで非ローカル `http://` API ベース URL を許可 |
-| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `OPENROUTER_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | プロバイダー認証 |
+| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `OPENROUTER_API_KEY` / `XIAOMI_MIMO_API_KEY` / `MIMO_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | プロバイダー認証 |
 | `OPENAI_BASE_URL` / `OPENAI_MODEL` | 汎用 OpenAI 互換エンドポイントとモデル ID |
 | `ATLASCLOUD_BASE_URL` / `ATLASCLOUD_MODEL` | AtlasCloud エンドポイントとモデル上書き |
 | `WANJIE_ARK_BASE_URL` / `WANJIE_ARK_MODEL` | Wanjie Ark エンドポイントとモデル上書き |
 | `OPENROUTER_BASE_URL` | OpenRouter エンドポイント上書き |
+| `XIAOMI_MIMO_BASE_URL` / `MIMO_BASE_URL` / `XIAOMI_MIMO_MODEL` / `MIMO_MODEL` | Xiaomi MiMo エンドポイントとモデル上書き |
 | `NOVITA_BASE_URL` | Novita エンドポイント上書き |
 | `FIREWORKS_BASE_URL` | Fireworks エンドポイント上書き |
 | `SGLANG_BASE_URL` | セルフホスト SGLang のエンドポイント |
@@ -349,10 +369,10 @@ UI のロケールはモデルの言語とは別です。`settings.toml` で `lo
 
 ## 自分のスキルを公開する
 
-codewhale はワークスペースのディレクトリ（`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills`）とグローバルな `~/.deepseek/skills` からスキルを発見します。各スキルは `SKILL.md` ファイルを持つディレクトリです:
+codewhale はワークスペースのディレクトリ（`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills`）とグローバルな `~/.codewhale/skills`（旧 `~/.deepseek/skills` も互換性維持）からスキルを発見します。各スキルは `SKILL.md` ファイルを持つディレクトリです:
 
 ```text
-~/.deepseek/skills/my-skill/
+~/.codewhale/skills/my-skill/
 └── SKILL.md
 ```
 
@@ -396,18 +416,6 @@ description: DeepSeek にカスタムワークフローを実行させたいと
 
 ---
 
-## サポート
-
-CodeWhale は MIT ライセンスで、利用やコントリビューションにスポンサーは必要ありません。
-継続的なメンテナンスを支援する最も分かりやすい方法は
-[GitHub Sponsors](https://github.com/sponsors/Hmbown) です。単発の支援は
-[Buy Me a Coffee](https://www.buymeacoffee.com/hmbown) からも行えます。
-
-スポンサーは、リリースビルド、CI/ランタイムテスト、パッケージ公開、issue 対応とレビューに使うメンテナー時間を支えます。
-機能リクエスト、バグ報告、pull request にスポンサーは必要ありません。
-
----
-
 ## 謝辞
 
 このプロジェクトは、増え続けるコントリビューターのコミュニティから助けを得て出荷されています:
@@ -422,7 +430,7 @@ CodeWhale は MIT ライセンスで、利用やコントリビューション
 - **[toi500](https://github.com/toi500)** — Windows 貼り付け修正の報告
 - **[xsstomy](https://github.com/xsstomy)** — ターミナル起動時の再描画報告
 - **[melody0709](https://github.com/melody0709)** — スラッシュ接頭辞の Enter アクティベーション報告
-- **[lloydzhou](https://github.com/lloydzhou)** と **[jeoor](https://github.com/jeoor)** — コンパクションコストの報告と npm インストーラのストリーム一時停止競合修正 (#1860)
+- **[lloydzhou](https://github.com/lloydzhou)** と **[jeoor](https://github.com/jeoor)** — コンパクションコストの報告
 - **[Agent-Skill-007](https://github.com/Agent-Skill-007)** — README の明瞭化対応 (#685)
 - **[woyxiang](https://github.com/woyxiang)** — Windows Scoop インストールドキュメント (#696)
 - **[wangfeng](mailto:wangfengcsu@qq.com)** — 料金／割引情報の更新 (#692)
@@ -430,108 +438,6 @@ CodeWhale は MIT ライセンスで、利用やコントリビューション
 - **Hafeez Pizofreude** — `fetch_url` の SSRF 保護と Star History チャート
 - **Unic (YuniqueUnic)** — スキーマ駆動の設定 UI（TUI + Web）
 - **Jason** — SSRF セキュリティの強化
-- **[dfwqdyl-ui](https://github.com/dfwqdyl-ui)** — モデル ID の大文字小文字互換性レポート (#729)
-- **[Oliver-ZPLiu](https://github.com/Oliver-ZPLiu)** — `working...` 状態のバグレポート、Windows クリップボードフォールバック、MCP Streamable HTTP セッション修正、Homebrew tap 自動化 (#738, #850, #1643, #1631)
-- **[reidliu41](https://github.com/reidliu41)** — 再開ヒント、ワークスペース信頼の永続化、Ollama プロバイダー対応、thinking-block ストリームの最終処理、CI キャッシュ強化、ストリーミングラップ、DeepSeek モデル補完、ヘルプ選択の改善 (#863, #870, #921, #1078, #1603, #1628, #1601, #1964)
-- **[cyq1017](https://github.com/cyq1017)** — Unicode `git_status` パス、ローカル/設定スキル検出、モード切替トーストの重複防止 (#1953, #1956, #1957)
-- **[xieshutao](https://github.com/xieshutao)** — プレーン Markdown スキルのフォールバック (#869)
-- **[GK012](https://github.com/GK012)** — npm ラッパー `--version` フォールバック (#885)
-- **[y0sif](https://github.com/y0sif)** — 直接子サブエージェント完了後の親ターンループ復帰 (#901)
-- **[mac119](https://github.com/mac119)** と **[leo119](https://github.com/leo119)** — `codewhale update` コマンドのドキュメント (#838, #917)
-- **[dumbjack](https://github.com/dumbjack)** — コマンド安全性の null バイト強化 (#706, #918)
-- **macworkers** — フォーク確認と新しいセッション ID (#600, #919)
-- **zero** と **[zerx-lab](https://github.com/zerx-lab)** — 通知条件設定と OSC 9 通知本文の拡充 (#820, #920)
-- **[chnjames](https://github.com/chnjames)** — @mention 補完キャッシュ、設定リカバリ改善、Windows UTF-8 シェル出力 (#849, #927, #982, #1018)
-- **[angziii](https://github.com/angziii)** — 設定安全性、非同期クリーンアップ、Docker 強化、コマンド安全性修正 (#822, #824, #827, #831, #833, #835, #837)
-- **[elowen53](https://github.com/elowen53)** — UTF-8 デコードと決定論的テストカバレッジ (#825, #840)
-- **[wdw8276](https://github.com/wdw8276)** — カスタムセッションタイトルの `/rename` コマンド (#836)
-- **[banqii](https://github.com/banqii)** — `.cursor/skills` 検出パス対応 (#817)
-- **[junskyeed](https://github.com/junskyeed)** — API リクエストの動的 `max_tokens` 計算 (#826)
-- **[axobase001](https://github.com/axobase001)** — スナップショット孤児クリーンアップ、npm インストールガード、セッションテレメトリ修正、モデルスコープキャッシュクリア、シンボリックリンクスキル対応、npm ミラー迂回ガイダンス、子タスクのプロキシ保持 (#975, #1032, #1047, #1049, #1052, #1019, #1051, #1056, #1608)
-- **[MengZ-super](https://github.com/MengZ-super)** — `/theme` コマンド基盤と SSE gzip/brotli 展開 (#1057, #1061)
-- **[DI-HUO-MING-YI](https://github.com/DI-HUO-MING-YI)** — Plan モードの読み取り専用サンドボックス安全性修正 (#1077)
-- **[bevis-wong](https://github.com/bevis-wong)** — ペースト Enter 自動送信の正確な再現 (#1073)
-- **[Duducoco](https://github.com/Duducoco)** と **[AlphaGogoo](https://github.com/AlphaGogoo)** — スキルスラッシュメニューと `/skills` 範囲修正 (#1068, #1083)
-- **[ArronAI007](https://github.com/ArronAI007)** — macOS Terminal.app と ConHost のウィンドウリサイズアーティファクト修正 (#993)
-- **[THINKER-ONLY](https://github.com/THINKER-ONLY)** — OpenRouter とカスタムエンドポイントのモデル ID 保持 (#1066)
-- **[Jefsky](https://github.com/Jefsky)** — DeepSeek エンドポイント修正レポート (#1079, #1084)
-- **[wlon](https://github.com/wlon)** — NVIDIA NIM プロバイダー API キー優先度診断 (#1081)
-- **[Horace Liu](https://github.com/liuhq)** — Nix パッケージ対応とインストールドキュメント (#1173)
-- **[jieshu666](https://github.com/jieshu666)** — ターミナル再描画のちらつき軽減 (#1563)
-- **[gordonlu](https://github.com/gordonlu)** — Windows Enter / CSI-u 入力修正 (#1612)
-- **[mdrkrg](https://github.com/mdrkrg)** — 初回起動時の API キー欠落クラッシュ修正 (#1598)
-- **[Aitensa](https://github.com/Aitensa)** — diff とページャー出力の CJK 折り返し対応 (#1622)
-- **[qiyan233](https://github.com/qiyan233)** — レガシー DeepSeek CN プロバイダーエイリアス互換性 (#1645)
-- **[zlh124](https://github.com/zlh124)** — WSL2/ヘッドレス起動レポートとクリップボード初期化修正 (#1772, #1773)
-- **[aboimpinto](https://github.com/aboimpinto)** — Windows alt-screen ログ、Home/End コンポーザー、ランタイムログフォローアップ (#1774, #1776, #1748, #1749, #1782, #1783)
-- **[LeoLin990405](https://github.com/LeoLin990405)** — プロバイダーモデル透過、推論リプレイ、thinking-only ターン、Windows 引用修正 (#1740, #1743, #1742, #1744)
-- **[nightt5879](https://github.com/nightt5879)** — Ctrl+C プロンプト復元修正 (#1764)
-- **[h3c-hexin](https://github.com/h3c-hexin)** — ストリーミングバッチツール呼び出し保存と CLI reasoning-effort 透過 (#1686, #1511)
-- **[hxy91819](https://github.com/hxy91819)** — ツール結果整理時のプレフィックスキャッシュ保持 (#1514)
-- **[JiarenWang](https://github.com/JiarenWang)** — Plan モード読み取り専用強制、承認引継ぎ最適化、Ctrl+H 削除修正、undo コンテキスト同期 (#1123, #962, #958, #1150)
-- **[Liu-Vince](https://github.com/Liu-Vince)** — MCP ページネーション、マークダウンインデント保持、zh-Hans i18n 改善、環境変数ドキュメント (#1256, #1179, #1274, #1178)
-- **[ChaceLyee2101](https://github.com/ChaceLyee2101)** — 推論トークンコスト集計と zh-Hans 自動 CNY 表示 (#1505, #1504)
-- **[laoye2020](https://github.com/laoye2020)** — Catppuccin、Tokyo Night、Dracula、Gruvbox テーマと `/theme` ピッカー (#1534)
-- **[punkcanyang](https://github.com/punkcanyang)** — Kitty (OSC 99) と Ghostty (OSC 777) デスクトップ通知対応 (#1426)
-- **[Rene-Kuhm](https://github.com/Rene-Kuhm)** — スペイン語 (es-419) ラテンアメリカローカライズ (#1452)
-- **[ComeFromTheMars](https://github.com/ComeFromTheMars)** — Shift+Up/Down トランスクリプトスクロールショートカット (#1432)
-- **[sockerch](https://github.com/sockerch)** — 全スラッシュコマンドの拼音エイリアス (#1306)
-- **[eltociear](https://github.com/eltociear)** — 日本語 README 翻訳 (#746)
-- **[Ling](https://github.com/LING71671)** — `grep_files` キャンセルトークン対応と Ctrl+Z コンポーザー下書き復元 (#1839, #1911)
-- **[Ben Younes](https://github.com/ousamabenyounes)** — Linux Wayland（非 wlroots）クリップボード対応 (#1938)
-- **[Matt Van Horn](https://github.com/mvanhorn)** — Docker 初回起動権限修正とランタイム system prompt 回帰テスト (#1699, #1702)
-- **[Kristopher Clark](https://github.com/krisclarkdev)** — compaction の user query 保持修正 (#1704)
-- **[tdccccc](https://github.com/tdccccc)** — コンポーザースクロール修正と pager マウスホイール対応 (#1715, #1716)
-- **[LittleBlacky](https://github.com/LittleBlacky)** — provider gated `reasoning_content` ストリーム修正 (#1680)
-- **[Anaheim](https://github.com/AnaheimEX)** — `rlm_open` 空 source schema 検証レポート (#1712)
-- **[THatch26](https://github.com/THatch26)** — ターミナル resize 後のページング修正 (#1724)
-- **[Alvin](https://github.com/alvin1)** — Zed ACP id 互換性レポート (#1696)
-- **[knqiufan](https://github.com/knqiufan)** — sub-agent ファイル書き込み委譲 (#1833)
-- **[IIzzaya](https://github.com/IIzzaya)** — slash 補完の exact alias 優先アイデア (#1811)
-- **[DC](https://github.com/duanchao-lab)** — ターミナル cleanup guard のアイデア (#1630)
-- **[imkingjh999](https://github.com/imkingjh999)** — provider/model 切り替え修正 (#1642)
-- **[Photo](https://github.com/eng2007)** — provider-aware `/model` picker catalog 作業 (#1201)
-- **[chennest](https://github.com/chennest)** — diagnostics schema レポート (#1685)
-- **[kunpeng-ai-lab](https://github.com/kunpeng-ai-lab)** — Windows コンポーザースクロール修正 (#1578)
-- **[WuMing](https://github.com/asdfg314284230)** — Windows PowerShell ちらつき修正 (#1591)
-- **[maker316](https://github.com/maker316)** — LoopGuard/checklist ループレポート (#1574)
-- **[lalala](https://github.com/lalala-233)** — approval denial 回帰レポート (#1617)
-- **[muyuliyan](https://github.com/muyuliyan)** — `pandoc_convert` 検証修正 (#1523)
-- **[czf0718](https://github.com/czf0718)** — resize と turn-completion のちらつき修正 (#1537)
-- **[MeAiRobot](https://github.com/MeAiRobot)** — toast がコンポーザー入力を覆う問題の修正 (#1485)
-- **[tiger-dog](https://github.com/tiger-dog)** — approval modal 折りたたみと markdown identifier 修正 (#1455)
-- **[MMMarcinho](https://github.com/MMMarcinho)** — opt-in `image_analyze` vision tool (#1467)
-- **[lucaszhu-hue](https://github.com/lucaszhu-hue)** — AtlasCloud provider 統合 (#1436)
-- **[sandofree](https://github.com/sandofree)** — Tavily と Bocha の `web_search` backend (#1294)
-- **[zhuangbiaowei](https://github.com/zhuangbiaowei)** — `/change` release notes コマンド (#1416)
-- **[NorethSea](https://github.com/NorethSea)** — updater companion binary refresh 修正 (#1492)
-- **[Jianfengwu2024](https://github.com/Jianfengwu2024)** — Windows MSVC toolchain 環境保持 (#1487)
-- **[Fire-dtx](https://github.com/Fire-dtx)** — npm postinstall recoverability 作業 (#1059)
-- **[oooyuy92](https://github.com/oooyuy92)** — 長時間セッション palette 可読性レポート (#1070, #936)
-- **[qinxianyuzou](https://github.com/qinxianyuzou)** — zh-Hans destructive approval 文言 (#1087, #1091)
-- **[tyouter](https://github.com/tyouter)** — session title/history preview クリーンアップ (#1510)
-- **[xulongzhe](https://github.com/xulongzhe)** — issue template と vision boundary follow-up (#1530, #1544)
-- **[YaYII](https://github.com/YaYII)** — trusted media path 作業 (#1462)
-- **[47Cid](https://github.com/47Cid)** と **[Jafar Akhondali](https://github.com/JafarAkhondali)** — 責任ある security disclosure と hardening レポート
-- **[linzhiqin2003](https://github.com/linzhiqin2003)** — `--model auto` コスト節約バイアス、実行規律プロンプト、宣言的事実メモリ衛生 (#1385, #1384, #1381)
-- **[lbcheng888](https://github.com/lbcheng888)** — 保存/復元間のコスト永続化とトランスクリプトスクロール修正 (#1192, #1211)
-- **[pengyou200902](https://github.com/pengyou200902)** — UTF-8 安全メモリ切り捨て、切り捨てマーカー精度、キーバインドドキュメント (#968, #1122, #1095)
-- **[CrepuscularIRIS](https://github.com/CrepuscularIRIS)** — Termius/SSH 向け低モーション検出と npx MCP サーバーサンドボックス修正 (#1479, #1346)
-- **[sternelee](https://github.com/sternelee)** — DeepSeek プレフィックスキャッシュ安定性追跡 (#1517)
-- **[Apeiron0w0](https://github.com/Apeiron0w0)** — Tabby ターミナルちらつきループの FocusGained デバウンス (#1560)
-- **[greyfreedom](https://github.com/greyfreedom)** — 最新トランスクリプトへのジャンプボタン (#969)
-- **[SamhandsomeLee](https://github.com/SamhandsomeLee)** — 明示的隠しファイルメンション補完 (#1270)
-- **[dst1213](https://github.com/dst1213)** — クォータエラー HTTP 400 リトライ (#1203)
-- **[fuleinist](https://github.com/fuleinist)** — `--yolo` フラグの CLI から TUI への転送 (#1233)
-- **[heloanc](https://github.com/heloanc)** — Home/End キーコンポーザーサポート (#1246)
-- **[jinpengxuan](https://github.com/jinpengxuan)** — オンボーディング中のアクティブプロバイダー認証情報保持 (#1265)
-- **[lixiasky-back](https://github.com/lixiasky-back)** — 検証済み npm バイナリ採用 (#1339)
-- **[J3y0r](https://github.com/J3y0r)** — ワークスペース切り替えコマンド (#1065)
-- **[KhalidAlnujaidi](https://github.com/KhalidAlnujaidi)** — delegate スキルバンドル (#1144)
-- **[Wenjunyun123](https://github.com/Wenjunyun123)** — ドキュメントアンカーオフセット保持 (#1282)
-- **[whtis](https://github.com/whtis)** — zh-CN README ディスパッチャーパス同期 (#1235)
-- **[aqilaziz](https://github.com/aqilaziz)** — memory スキルリンク修正 (#1095)
-- **[wuwuzhijing](https://github.com/wuwuzhijing)** — rsproxy rustup 回避策インストールドキュメント (#1011)
 
 ---
 
diff --git a/README.md b/README.md
index 58975408..5d908629 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,20 @@
 # CodeWhale
 
-> DeepSeek-first agentic terminal for open source and open-weight coding models. It runs from the `codewhale` command, streams reasoning blocks, edits local workspaces with approval gates, and can auto-route each turn to the right DeepSeek model and thinking level.
-
-[![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale)
-[![crates.io](https://img.shields.io/crates/v/codewhale-cli?label=crates.io)](https://crates.io/crates/codewhale-cli)
-[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Hmbown)
-[DeepWiki project index](https://deepwiki.com/Hmbown/CodeWhale)
+> Terminal coding agent for DeepSeek V4. It runs from the `codewhale` command, streams reasoning blocks, edits local workspaces with approval gates, and includes an auto mode that chooses both model and thinking level per turn.
 
 [简体中文 README](README.zh-CN.md)
 [日本語 README](README.ja-JP.md)
+[Tiếng Việt README](README.vi.md)
 
-[Install](#install) · [Quickstart](#quickstart) · [Usage](#usage) · [Documentation](#documentation) · [Contributing](#contributing) · [Support](#support)
 
 ## Install
 
-`codewhale` is distributed as Rust binaries: the dispatcher command
-(`codewhale`) and the companion TUI runtime (`codewhale-tui`). Pick whichever
-install path you already use; they all put the same commands on your `PATH`.
-The npm package is an installer/wrapper for the release binaries, not the
-agent runtime itself.
+`codewhale` installs as a matched pair of self-contained Rust release binaries:
+the `codewhale` dispatcher command and the sibling `codewhale-tui` runtime it
+launches for interactive sessions. npm, Homebrew, and Docker install both for
+you; Cargo and manual installs must put both binaries in the same directory
+(normally a directory on your `PATH`). The npm package is only an
+installer/wrapper for those release binaries; the agent does not run on Node.
 
 ```bash
 # 1. npm — easiest if you already use Node. The package downloads the
@@ -33,18 +28,20 @@ cargo install codewhale-cli --locked   # `codewhale` (entry point)
 cargo install codewhale-tui     --locked   # `codewhale-tui` (TUI binary)
 
 # 3. Homebrew — macOS package manager.
+#    The tap/formula name is legacy; it installs codewhale and codewhale-tui.
 brew tap Hmbown/deepseek-tui
 brew install deepseek-tui
 
-# 4. Direct download — no package manager or toolchain.
+# 4. Direct download — platform archive from GitHub Releases.
 #    https://github.com/Hmbown/CodeWhale/releases
-#    Prebuilt for Linux x64/ARM64, macOS x64/ARM64, Windows x64.
+#    Archives include both codewhale and codewhale-tui plus an install script.
+#    Individual binaries are also attached for scripts; keep the pair together.
 
 # 5. Docker — prebuilt release image.
 docker volume create codewhale-home
 docker run --rm -it \
   -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-  -v codewhale-home:/home/codewhale/.deepseek \
+  -v codewhale-home:/home/codewhale/.codewhale \
   -v "$PWD:/workspace" \
   -w /workspace \
   ghcr.io/hmbown/codewhale:latest
@@ -69,44 +66,93 @@ cargo install codewhale-cli --locked --force
 cargo install codewhale-tui     --locked --force
 ```
 
+> codewhale update now supports --proxy, update through a proxy
+> eg: codewhale update --proxy https://localhost:7897
+
+[![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale)
+[![crates.io](https://img.shields.io/crates/v/codewhale-cli?label=crates.io)](https://crates.io/crates/codewhale-cli)
+[DeepWiki project index](https://deepwiki.com/Hmbown/CodeWhale)
+
 ![codewhale screenshot](assets/screenshot.png)
 
 ---
 
 ## What Is It?
 
-CodeWhale is a DeepSeek-first coding agent for open source and open-weight models that runs in your terminal. It can read and edit files, run shell commands, search the web, manage git, and coordinate sub-agents from a keyboard-driven TUI.
+A model answers a question. An agent finishes a task. The difference is
+the harness — a system of rules, evidence, and feedback that keeps the
+model oriented instead of drifting.
 
-It is built around DeepSeek V4 (`deepseek-v4-pro` / `deepseek-v4-flash`), including 1M-token context windows, streaming reasoning blocks, and prefix-cache-aware cost reporting.
+CodeWhale is that harness, built around DeepSeek V4 and guided by three ideas:
 
-### Key Features
+| Principle | How it works |
+|---|---|
+| **Start with trust** | Every turn begins with "A" — possibility before certainty, craft before convenience |
+| **Clear jurisdiction** | A written Constitution with nine tiers of authority. User intent outranks stale instructions. Verification outranks confidence. |
+| **Recursive improvement** | V4 helped write the harness. As the harness improves, V4 becomes more effective — and helps improve the harness further. Each turn starts stronger. |
 
-- **Model auto-routing** — `--model auto` / `/model auto` chooses both the model and thinking level for each turn
-- **Thinking-mode streaming** — see DeepSeek reasoning blocks as the model works
-- **Full tool suite** — file ops, shell execution, git, web search/browse, apply-patch, sub-agents, MCP servers
-- **1M-token context** — context tracking, manual or configured compaction, and prefix-cache telemetry
-- **Prefix-cache stability tracking** — an optional `/statusline` footer chip surfaces how stable the cached prefix has been across recent turns so cost-busting edits are visible before they land
-- **Three modes** — Plan (read-only explore), Agent (interactive with approval), YOLO (auto-approved)
-- **Reasoning-effort tiers** — cycle through `off → high → max` with `Shift + Tab`
-- **Session save/resume/fork** — checkpoint long-running sessions and fork saved conversations into sibling paths with parent lineage shown in the picker
-- **Workspace rollback** — side-git pre/post-turn snapshots with `/restore` and `revert_turn`, without touching your repo's `.git`
-- **OS-level sandbox** — Seatbelt on macOS, Landlock on Linux, Job Objects on Windows; shell commands run with workspace-scoped filesystem access only
-- **Durable task queue** — background tasks can survive restarts
-- **HTTP/SSE runtime API** — `codewhale serve --http` for headless agent workflows
-- **MCP protocol** — connect to Model Context Protocol servers for extended tooling; please see [docs/MCP.md](docs/MCP.md)
-- **Fin-powered seams** — cheap `deepseek-v4-flash` with thinking off handles routing, RLM child calls, summaries, and other fast coordination work
-- **Native RLM** (`rlm_session_objects`/`rlm_open`/`rlm_eval`) — persistent REPL sessions for batched analysis with bounded helpers like `peek`, `search`, `chunk`, and `sub_query_batch`; active prompt/history objects are opened by symbolic refs instead of pasted into the parent transcript
-- **LSP diagnostics** — inline error/warning surfacing after every edit via rust-analyzer, pyright, typescript-language-server, gopls, clangd
-- **User memory** — optional persistent note file injected into the system prompt for cross-session preferences
-- **Localized UI** — `en`, `ja`, `zh-Hans`, `pt-BR` with auto-detection
-- **Live cost tracking** — per-turn and session-level token usage and cost estimates; cache hit/miss breakdown; CNY display when the session locale is `zh-Hans`
-- **Skills system** — composable, installable instruction packs from GitHub; ships with a bundled starter set (`skill-creator`, `mcp-builder`, `plugin-creator`, `v4-best-practices`, `documents`, `presentations`, `spreadsheets`, `pdf`, `feishu`, `skill-installer`, `delegate`) so `/skills` is useful from first launch
-- **Terminal-native notifications** — OSC 9 (iTerm2/WezTerm/Ghostty), OSC 99 (Kitty), OSC 777 (Ghostty), plus desktop notification fallback
-- **Built-in theme picker** — Catppuccin, Tokyo Night, Dracula, Gruvbox alongside the original light/dark palettes; switch live with `/theme`
+It's open source, terminal-native, and packaged as a matched `codewhale` /
+`codewhale-tui` Rust binary pair.
+
+## How the Harness Works
+
+Agentic models deal with conflicting information at scale: user intent,
+project rules, system defaults, tool output, and stale memory all compete
+for authority in a single turn. LLM-as-a-judge needs jurisdiction — which
+source wins when they disagree?
+
+CodeWhale answers this with a **Constitution** (`prompts/base.md`). It's a
+formal hierarchy of law — Article VII ranks nine sources from the
+Constitution's own articles down to prior-session handoffs. The user's
+current message outranks stale project instructions. Live tool output
+outranks assumptions. Verification outranks confidence. The model inherits
+a clear chain of authority every turn and never has to guess which
+directive to follow.
+
+Seven articles sit above the hierarchy, defining the model's identity,
+duties, and agency: a verification mandate (Article V — every action leaves
+evidence, never declare success on faith), a coordination legacy (Article
+VI — leave the workspace legible for the next intelligence), and a
+primacy-of-truth clause (Article II — no lower rule may override it).
+
+DeepSeek V4's prefix caching makes this practical. The Constitution is long
+and detailed, but once cached it costs roughly 100× less per turn than a
+cold read. The model references it recursively — peeking, scanning, and
+querying through RLM sessions — revisiting information on demand rather
+than relying on a single memorized pass. It performs more like an
+open-book test than a closed one.
+
+Because the authority structure is explicit, failure isn't hidden. Non-zero
+exit codes, type errors from rust-analyzer arriving between turns, sandbox
+denials — these are fed back as correction vectors. The model uses its own
+drift to self-correct.
+
+Three modes control the action space. Plan is read-only. Agent gates
+destructive operations behind approval. YOLO auto-approves in trusted
+workspaces. macOS Seatbelt is the active sandbox; Linux Landlock is
+detected but not yet enforced; Windows sandboxing is not yet advertised.
+
+Fin — a cheap Flash call with thinking off — handles model auto-routing per
+turn. `--model auto` is the default.
+
+Every turn records a side-git snapshot outside your repo's `.git`.
+`/restore` and `revert_turn` roll back the workspace.
+
+Sub-agents run concurrently (up to 20). `agent_open` returns immediately;
+results arrive inline as completion sentinels with a summary. Full
+transcripts stay behind bounded handles through `agent_eval`. See
+[docs/SUBAGENTS.md](docs/SUBAGENTS.md).
+
+The rest of the surface: LSP diagnostics after every edit (rust-analyzer,
+pyright, typescript-language-server, gopls, clangd, jdtls,
+vue-language-server), RLM sessions for batched analysis, MCP protocol,
+HTTP/SSE runtime API, persistent task queue, ACP adapter for Zed,
+SWE-bench export, and live cost tracking with cache hit/miss breakdowns.
 
 ---
 
-## How It's Wired
+## The Harness
 
 `codewhale` (dispatcher CLI) → `codewhale-tui` (companion binary) → ratatui interface ↔ async engine ↔ OpenAI-compatible streaming client. Tool calls route through a typed registry (shell, file ops, git, web, sub-agents, MCP, RLM) and results stream back into the transcript. The engine manages session state, turn tracking, the durable task queue, and an LSP subsystem that feeds post-edit diagnostics into the model's context before the next reasoning step.
 
@@ -118,8 +164,8 @@ CodeWhale can dispatch multiple sub-agents that run in parallel — like a concu
 
 - **Non-blocking launch.** `agent_open` returns immediately. The child gets its own fresh context and tool registry and runs independently. The parent keeps working.
 - **Background execution.** Sub-agents execute concurrently (default cap: 10, configurable to 20). The engine manages the pool — no polling loop needed.
-- **Completion notification.** When a sub-agent finishes, the runtime delivers a structured `<codewhale:subagent.done>` event with a summary, evidence list, and execution metrics. The parent model reads the `summary` field and integrates findings.
-- **Bounded result retrieval.** Large transcripts are parked behind `var_handle` references. The model calls `handle_read` for slices, ranges, or JSONPath projections — keeping the parent context lean.
+- **Completion notification.** When a sub-agent finishes, the runtime injects a `<codewhale:subagent.done>` sentinel into the parent's transcript. The human-readable summary — including the child's findings, changed files, and any risks — sits on the line immediately before the sentinel. The parent model reads that summary and integrates findings without an extra tool call.
+- **Bounded result retrieval.** The full child transcript lives behind a `transcript_handle` accessible through `agent_eval`. When the summary isn't enough, the parent calls `handle_read` for slices, line ranges, or JSONPath projections — keeping the parent context lean without losing access to the details.
 
 See [docs/SUBAGENTS.md](docs/SUBAGENTS.md) for the full sub-agent reference.
 
@@ -133,14 +179,14 @@ codewhale --version
 codewhale --model auto
 ```
 
-Prebuilt binaries are published for **Linux x64**, **Linux ARM64** (v0.8.8+), **macOS x64**, **macOS ARM64**, and **Windows x64**. For other targets (musl, riscv64, FreeBSD, etc.), see [Install from source](#install-from-source) or [docs/INSTALL.md](docs/INSTALL.md).
+Prebuilt binary pairs and platform archives are published for **Linux x64**, **Linux ARM64** (v0.8.8+), **macOS x64**, **macOS ARM64**, and **Windows x64**. For other targets (musl, riscv64, FreeBSD, etc.), see [Install from source](#install-from-source) or [docs/INSTALL.md](docs/INSTALL.md).
 
-On first launch you'll be prompted for your [DeepSeek API key](https://platform.deepseek.com/api_keys). The key is saved to `~/.deepseek/config.toml` so it works from any directory without OS credential prompts.
+On first launch you'll be prompted for your [DeepSeek API key](https://platform.deepseek.com/api_keys). The key is saved to `~/.codewhale/config.toml` (legacy `~/.deepseek/config.toml` also supported) so it works from any directory without OS credential prompts.
 
 You can also set it ahead of time:
 
 ```bash
-codewhale auth set --provider deepseek   # saves to ~/.deepseek/config.toml
+codewhale auth set --provider deepseek   # saves to ~/.codewhale/config.toml
 codewhale auth status                    # shows the active credential source
 
 export DEEPSEEK_API_KEY="YOUR_KEY"      # env var alternative; use ~/.zshenv for non-interactive shells
@@ -168,18 +214,18 @@ Start with [docs/TENCENT_CLOUD_REMOTE_FIRST.md](docs/TENCENT_CLOUD_REMOTE_FIRST.
 then use [docs/TENCENT_LIGHTHOUSE_HK.md](docs/TENCENT_LIGHTHOUSE_HK.md) for the
 server runbook.
 
-### Model Auto-Routing and Fin
+### Auto Mode
 
 Use `codewhale --model auto` or `/model auto` when you want codewhale to decide how much model and reasoning power a turn needs.
 
-Model auto-routing controls two settings together:
+Auto mode controls two settings together:
 
 - Model: `deepseek-v4-flash` or `deepseek-v4-pro`
 - Thinking: `off`, `high`, or `max`
 
-Before the real turn is sent, the app makes a small `deepseek-v4-flash` routing call with thinking off. That fast path is called **Fin**: a low-latency seam for model selection, summaries, RLM children, context maintenance, and other coordination work that should not spend a full reasoning turn. Fin looks at the latest request and recent context, then selects a concrete model and thinking level for the real request. Short/simple turns can stay on Flash with thinking off; coding, debugging, release work, architecture, security review, or ambiguous multi-step tasks can move up to Pro and/or higher thinking.
+Before the real turn is sent, the app makes a small `deepseek-v4-flash` routing call with thinking off. That router looks at the latest request and recent context, then selects a concrete model and thinking level for the real request. Short/simple turns can stay on Flash with thinking off; coding, debugging, release work, architecture, security review, or ambiguous multi-step tasks can move up to Pro and/or higher thinking.
 
-`--model auto` and `/model auto` are local to codewhale. The upstream API never receives `model: "auto"`; it receives the concrete model and thinking setting chosen for that turn. The TUI shows the selected route, and cost tracking is charged against the model that actually ran. If the Fin route fails or returns an invalid answer, the app falls back to a local heuristic. Sub-agents inherit model auto-routing unless you assign them an explicit model.
+`auto` is local to codewhale. The upstream API never receives `model: "auto"`; it receives the concrete model and thinking setting chosen for that turn. The TUI shows the selected route, and cost tracking is charged against the model that actually ran. If the router call fails or returns an invalid answer, the app falls back to a local heuristic. Sub-agents inherit auto mode unless you assign them an explicit model.
 
 Use a fixed model or fixed thinking level when you want repeatable benchmarking, a strict cost ceiling, or a specific provider/model mapping.
 
@@ -219,7 +265,7 @@ version with `codewhale --version`:
 
 ```bash
 scoop update
-scoop install deepseek-tui
+scoop install codewhale
 codewhale --version
 ```
 
@@ -250,9 +296,8 @@ Both binaries are required. Cross-compilation and platform-specific notes: [docs
 
 ### Other API Providers
 
-Official DeepSeek remains the default and first-class path. Other providers are
-additive, with OpenRouter starting from DeepSeek Pro/Flash before broader
-open-model catalogs are enabled.
+For the full shipped provider registry, including model IDs, auth variables,
+base URLs, and capability boundaries, see [docs/PROVIDERS.md](docs/PROVIDERS.md).
 
 ```bash
 # NVIDIA NIM
@@ -271,6 +316,10 @@ codewhale --provider wanjie-ark --model deepseek-reasoner
 codewhale auth set --provider openrouter --api-key "YOUR_OPENROUTER_API_KEY"
 codewhale --provider openrouter --model deepseek/deepseek-v4-pro
 
+# Xiaomi MiMo
+codewhale auth set --provider xiaomi-mimo --api-key "YOUR_XIAOMI_MIMO_API_KEY"
+codewhale --provider xiaomi-mimo --model mimo-v2.5-pro
+
 # Novita
 codewhale auth set --provider novita --api-key "YOUR_NOVITA_API_KEY"
 codewhale --provider novita --model deepseek/deepseek-v4-pro
@@ -283,11 +332,18 @@ codewhale --provider fireworks --model deepseek-v4-pro
 codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"
 OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model glm-5
 
+# Custom DeepSeek-compatible endpoint
+DEEPSEEK_BASE_URL="https://your-provider.example/v1" \
+  DEEPSEEK_MODEL="deepseek-ai/DeepSeek-V4-Pro" \
+  codewhale --provider deepseek
+
 # Self-hosted SGLang
 SGLANG_BASE_URL="http://localhost:30000/v1" codewhale --provider sglang --model deepseek-v4-flash
 
 # Self-hosted vLLM
 VLLM_BASE_URL="http://localhost:8000/v1" codewhale --provider vllm --model deepseek-v4-flash
+# Trusted LAN vLLM over HTTP
+DEEPSEEK_ALLOW_INSECURE_HTTP=1 VLLM_BASE_URL="http://192.168.0.110:8000/v1" codewhale --provider vllm --model deepseek-v4-flash
 
 # Self-hosted Ollama
 ollama pull codewhale-coder:1.3b
@@ -311,17 +367,13 @@ interfaces, and extension points.
 
 ## Usage
 
-All examples use `codewhale`. The short form `codew` works everywhere —
-it's a silent alias that forwards to `codewhale`.
-
 ```bash
 codewhale                                         # interactive TUI
 codewhale "explain this function"                 # one-shot prompt
-codewhale exec --auto --output-format stream-json "fix this bug"  # agentic exec with tool auto-approvals
-codewhale swebench run --instance-id <ID> --issue-file issue.md  # write all_preds.jsonl for SWE-bench
+codewhale exec --auto --output-format stream-json "fix this bug"  # NDJSON backend stream
 codewhale exec --resume <SESSION_ID> "follow up"  # continue a non-interactive session
 codewhale --model deepseek-v4-flash "summarize"   # model override
-codewhale --model auto "fix this bug"             # auto-route model + thinking
+codewhale --model auto "fix this bug"             # auto-select model + thinking
 codewhale --yolo                                  # auto-approve tools
 codewhale auth set --provider deepseek            # save API key
 codewhale doctor                                  # check setup & connectivity
@@ -334,6 +386,7 @@ codewhale resume --last                           # resume the most recent sessi
 codewhale resume <SESSION_ID>                     # resume a specific session by UUID
 codewhale fork <SESSION_ID>                       # fork a saved session into a sibling path
 codewhale serve --http                            # HTTP/SSE API server
+codewhale serve --mobile                          # LAN mobile control page; token-gated by default
 codewhale serve --acp                             # ACP stdio adapter for Zed/custom agents
 codewhale run pr <N>                              # fetch PR and pre-seed review prompt
 codewhale mcp list                                # list configured MCP servers
@@ -362,7 +415,7 @@ docker volume create codewhale-home
 
 docker run --rm -it \
   -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-  -v codewhale-home:/home/codewhale/.deepseek \
+  -v codewhale-home:/home/codewhale/.codewhale \
   -v "$PWD:/workspace" \
   -w /workspace \
   ghcr.io/hmbown/codewhale:latest
@@ -371,23 +424,6 @@ docker run --rm -it \
 See [docs/DOCKER.md](docs/DOCKER.md) for pinned tags, local image builds,
 volume ownership notes, and non-interactive pipeline usage.
 
-### SWE-bench
-
-CodeWhale can emit SWE-bench-compatible prediction JSONL from a checked-out
-task workspace:
-
-```bash
-codewhale swebench run \
-  --instance-id django__django-12345 \
-  --issue-file issue.md \
-  --predictions-path all_preds.jsonl
-```
-
-`run` uses the same tool-backed automation path as `codewhale exec --auto`,
-then exports the final working-tree diff as `model_patch`. Use
-`codewhale swebench export --instance-id <ID>` when you have already produced
-the diff yourself. See [docs/SWEBENCH.md](docs/SWEBENCH.md) for the full flow.
-
 ### Zed / ACP
 
 DeepSeek can run as a custom Agent Client Protocol server for editors that
@@ -429,11 +465,6 @@ ACP workflows outside the built-in Zed slice.
 | `@path` | Attach file/directory context in composer |
 | `↑` (at composer start) | Select attachment row for removal |
 
-Voice input is available from the command palette (`Ctrl+K`, then search
-`Voice input`) after configuring `voice_input_command`; the helper
-records/transcribes audio, CodeWhale shows a listening status while it runs, and
-the final transcript is inserted into the composer for editing.
-
 Full shortcut catalog: [docs/KEYBINDINGS.md](docs/KEYBINDINGS.md).
 
 ---
@@ -446,17 +477,17 @@ Full shortcut catalog: [docs/KEYBINDINGS.md](docs/KEYBINDINGS.md).
 | **Agent** 🤖 | Default interactive mode — multi-step tool use with approval gates; substantial work is tracked with `checklist_write` |
 | **YOLO** ⚡ | Auto-approve all tools in a trusted workspace; multi-step work still keeps a visible checklist |
 
-Modes are separate from model auto-routing. `Tab` cycles Plan / Agent / YOLO,
-while `/model auto` controls model and thinking selection. The `/goal` command
-tracks a session objective and token budget today; a fuller Goal work surface is
-the right future home for persistent objective progress rather than another
-meaning of "auto".
-
 ---
 
 ## Configuration
 
-User config: `~/.deepseek/config.toml`. Project overlay: `<workspace>/.deepseek/config.toml` (denied: `api_key`, `base_url`, `provider`, `mcp_config_path`). [config.example.toml](config.example.toml) has every option.
+User config: `~/.codewhale/config.toml` (legacy `~/.deepseek/config.toml` fallback). Project overlay: `<workspace>/.codewhale/config.toml` (legacy `<workspace>/.deepseek/config.toml`) (denied: `api_key`, `base_url`, `provider`, `mcp_config_path`). [config.example.toml](config.example.toml) has every option.
+
+Custom DeepSeek-compatible endpoints usually do not need a new provider. Keep
+`provider = "deepseek"` and set `[providers.deepseek].base_url` / `model`, or
+use `provider = "openai"` for generic OpenAI-compatible gateways. Keep
+`provider`, `api_key`, and `base_url` in user config or environment variables;
+project overlays cannot set them.
 
 Key environment variables:
 
@@ -467,15 +498,16 @@ Key environment variables:
 | `DEEPSEEK_HTTP_HEADERS` | Optional custom model request headers, e.g. `X-Model-Provider-Id=your-model-provider` |
 | `DEEPSEEK_MODEL` | Default model |
 | `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` | Stream idle timeout in seconds, default `300`, clamped to `1..=3600` |
-| `DEEPSEEK_PROVIDER` | `codewhale` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `novita`, `fireworks`, `sglang`, `vllm`, `ollama` |
+| `CODEWHALE_PROVIDER` / `DEEPSEEK_PROVIDER` | `deepseek` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `volcengine`, `openrouter`, `xiaomi-mimo`, `novita`, `fireworks`, `moonshot`, `sglang`, `vllm`, `ollama` |
 | `DEEPSEEK_PROFILE` | Config profile name |
 | `DEEPSEEK_MEMORY` | Set to `on` to enable user memory |
 | `DEEPSEEK_ALLOW_INSECURE_HTTP=1` | Allow non-local `http://` API base URLs on trusted networks |
-| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `OPENROUTER_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | Provider auth |
+| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `VOLCENGINE_API_KEY` / `OPENROUTER_API_KEY` / `XIAOMI_MIMO_API_KEY` / `MIMO_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `MOONSHOT_API_KEY` / `KIMI_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | Provider auth |
 | `OPENAI_BASE_URL` / `OPENAI_MODEL` | Generic OpenAI-compatible endpoint and model ID |
 | `ATLASCLOUD_BASE_URL` / `ATLASCLOUD_MODEL` | AtlasCloud endpoint and model override |
 | `WANJIE_ARK_BASE_URL` / `WANJIE_ARK_MODEL` | Wanjie Ark endpoint and model override |
 | `OPENROUTER_BASE_URL` | OpenRouter endpoint override |
+| `XIAOMI_MIMO_BASE_URL` / `MIMO_BASE_URL` / `XIAOMI_MIMO_MODEL` / `MIMO_MODEL` | Xiaomi MiMo endpoint and model override |
 | `NOVITA_BASE_URL` | Novita endpoint override |
 | `FIREWORKS_BASE_URL` | Fireworks endpoint override |
 | `SGLANG_BASE_URL` | Self-hosted SGLang endpoint |
@@ -509,7 +541,7 @@ Legacy aliases `deepseek-chat` / `deepseek-reasoner` map to `deepseek-v4-flash`
 
 ## Publishing Your Own Skill
 
-codewhale discovers skills from workspace directories (`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills` → `.cursor/skills`) and global directories (`~/.agents/skills` → `~/.claude/skills` → `~/.deepseek/skills`). Each skill is a directory with a `SKILL.md` file:
+codewhale discovers skills from workspace directories (`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills` → `.cursor/skills`) and global directories (`~/.agents/skills` → `~/.claude/skills` → `~/.codewhale/skills` → `~/.deepseek/skills`). Each skill is a directory with a `SKILL.md` file:
 
 ```text
 ~/.agents/skills/my-skill/
@@ -534,7 +566,7 @@ First launch also installs bundled system skills for common workflows:
 `skill-creator`, `delegate`, `v4-best-practices`, `plugin-creator`,
 `skill-installer`, `mcp-builder`, `documents`, `presentations`,
 `spreadsheets`, `pdf`, and `feishu`. These live under
-`~/.deepseek/skills` and are versioned so new bundles are added on upgrade
+`~/.codewhale/skills` (or legacy `~/.deepseek/skills`) and are versioned so new bundles are added on upgrade
 without recreating skills the user deliberately deleted.
 
 ---
@@ -543,11 +575,13 @@ without recreating skills the user deliberately deleted.
 
 | Doc | Topic |
 |---|---|
+| [GUIDE.md](docs/GUIDE.md) | First-run user guide |
 | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Codebase internals |
 | [CONFIGURATION.md](docs/CONFIGURATION.md) | Full config reference |
+| [PROVIDERS.md](docs/PROVIDERS.md) | Provider IDs, auth, model defaults, and capability metadata |
 | [MODES.md](docs/MODES.md) | Plan / Agent / YOLO modes |
 | [MCP.md](docs/MCP.md) | Model Context Protocol integration |
-| [RUNTIME_API.md](docs/RUNTIME_API.md) | HTTP/SSE API server |
+| [RUNTIME_API.md](docs/RUNTIME_API.md) | HTTP/SSE API server and mobile control page |
 | [INSTALL.md](docs/INSTALL.md) | Platform-specific install guide |
 | [DOCKER.md](docs/DOCKER.md) | GHCR image, volumes, and Docker usage |
 | [CNB_MIRROR.md](docs/CNB_MIRROR.md) | CNB mirror and China-friendly install notes |
@@ -559,25 +593,11 @@ without recreating skills the user deliberately deleted.
 | [RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) | Release process |
 | [LOCALIZATION.md](docs/LOCALIZATION.md) | UI locale matrix & switching |
 | [OPERATIONS_RUNBOOK.md](docs/OPERATIONS_RUNBOOK.md) | Ops & recovery |
-| [RECURSIVE_SELF_IMPROVEMENT.md](docs/RECURSIVE_SELF_IMPROVEMENT.md) | Copyable prompts for agent-assisted CodeWhale improvements |
 
 Full Changelog: [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
-## Support
-
-CodeWhale is MIT-licensed and usable without sponsorship. If it saves you time,
-the clearest way to support ongoing maintenance is
-[GitHub Sponsors](https://github.com/sponsors/Hmbown). One-time support is also
-available through [Buy Me a Coffee](https://www.buymeacoffee.com/hmbown).
-
-Sponsorship helps cover release builds, CI/runtime testing, package publishing,
-and maintainer time for issue triage and review. Feature requests, bug reports,
-and pull requests do not require sponsorship.
-
----
-
 ## Thanks
 
 - **[DeepSeek](https://github.com/deepseek-ai)** — thank you for the models and support that power every turn. 感谢 DeepSeek 提供模型与支持，让每一次交互成为可能。
@@ -597,15 +617,14 @@ This project ships with help from a growing community of contributors:
 - **[toi500](https://github.com/toi500)** — Windows paste fix report
 - **[xsstomy](https://github.com/xsstomy)** — Terminal startup repaint report
 - **[melody0709](https://github.com/melody0709)** — Slash-prefix Enter activation report
-- **[lloydzhou](https://github.com/lloydzhou)** and **[jeoor](https://github.com/jeoor)** — Compaction cost reports and npm installer stream-pause race fix (#1860); lloydzhou also contributed deterministic environment context (#813, #922) and KV prefix-cache stabilisation (#1080)
+- **[lloydzhou](https://github.com/lloydzhou)** and **[jeoor](https://github.com/jeoor)** — Compaction cost reports; lloydzhou also contributed deterministic environment context (#813, #922) and KV prefix-cache stabilisation (#1080)
 - **[Agent-Skill-007](https://github.com/Agent-Skill-007)** — README clarity pass (#685)
 - **[woyxiang](https://github.com/woyxiang)** — Windows install documentation (#696)
 - **[wangfeng](mailto:wangfengcsu@qq.com)** — Pricing/discount info update (#692)
 - **[zichen0116](https://github.com/zichen0116)** — CODE_OF_CONDUCT.md (#686)
 - **[dfwqdyl-ui](https://github.com/dfwqdyl-ui)** — model ID case-sensitivity compatibility report (#729)
 - **[Oliver-ZPLiu](https://github.com/Oliver-ZPLiu)** — stale `working...` state bug report, Windows clipboard fallback, MCP Streamable HTTP session fixes, and Homebrew tap automation (#738, #850, #1643, #1631)
-- **[reidliu41](https://github.com/reidliu41)** — resume hint, workspace trust persistence, Ollama provider support, thinking-block stream finalization, CI cache hardening, streaming wrap, DeepSeek model completions, and help picker selection polish (#863, #870, #921, #1078, #1603, #1628, #1601, #1964)
-- **[cyq1017](https://github.com/cyq1017)** — Unicode `git_status` paths, local/configured skill discovery, and mode-switch toast dedupe (#1953, #1956, #1957)
+- **[reidliu41](https://github.com/reidliu41)** — resume hint, workspace trust persistence, Ollama provider support, thinking-block stream finalization, CI cache hardening, streaming wrap, and DeepSeek model completions (#863, #870, #921, #1078, #1603, #1628, #1601)
 - **[xieshutao](https://github.com/xieshutao)** — plain Markdown skill fallback (#869)
 - **[GK012](https://github.com/GK012)** — npm wrapper `--version` fallback (#885)
 - **[y0sif](https://github.com/y0sif)** — parent turn-loop wakeup after direct child sub-agent completion (#901)
@@ -641,72 +660,16 @@ This project ships with help from a growing community of contributors:
 - **[aboimpinto](https://github.com/aboimpinto)** — Windows alt-screen logging, Home/End composer, and runtime log follow-ups (#1774, #1776, #1748, #1749, #1782, #1783)
 - **[LeoLin990405](https://github.com/LeoLin990405)** — provider model passthrough, reasoning replay, thinking-only turn, and Windows quoting fixes (#1740, #1743, #1742, #1744)
 - **[nightt5879](https://github.com/nightt5879)** — Ctrl+C prompt restore fix (#1764)
-- **[h3c-hexin](https://github.com/h3c-hexin)** — streaming batch tool-call preservation and CLI reasoning-effort passthrough (#1686, #1511)
-- **[hxy91819](https://github.com/hxy91819)** — prefix-cache preservation during tool-result pruning (#1514)
-- **[JiarenWang](https://github.com/JiarenWang)** — Plan-mode read-only enforcement, approval-takeover clamping, Ctrl+H delete fix, and undo context sync (#1123, #962, #958, #1150)
-- **[Liu-Vince](https://github.com/Liu-Vince)** — MCP pagination, markdown indentation preservation, zh-Hans i18n polish, and env-var documentation (#1256, #1179, #1274, #1178)
-- **[linzhiqin2003](https://github.com/linzhiqin2003)** — `--model auto` cost-saving bias, execution-discipline prompts, and declarative-fact memory hygiene (#1385, #1384, #1381)
-- **[lbcheng888](https://github.com/lbcheng888)** — cost persistence across save/restore and transcript scroll fix (#1192, #1211)
-- **[pengyou200902](https://github.com/pengyou200902)** — UTF-8-safe memory truncation, truncation-marker precision, and keybinding docs (#968, #1122, #1095)
-- **[ChaceLyee2101](https://github.com/ChaceLyee2101)** — reasoning-token cost tracking with auto-CNY on zh-Hans and zh-CN README sync (#1505, #1504)
-- **[CrepuscularIRIS](https://github.com/CrepuscularIRIS)** — low-motion mode for Termius/SSH and npx MCP server sandbox fix (#1479, #1346)
-- **[laoye2020](https://github.com/laoye2020)** — Catppuccin, Tokyo Night, Dracula, and Gruvbox themes with `/theme` picker (#1534)
-- **[punkcanyang](https://github.com/punkcanyang)** — Kitty (OSC 99) and Ghostty (OSC 777) desktop notification support (#1426)
-- **[Rene-Kuhm](https://github.com/Rene-Kuhm)** — Spanish (es-419) Latin American localization (#1452)
-- **[sternelee](https://github.com/sternelee)** — DeepSeek prefix-cache stability tracking (#1517)
-- **[ComeFromTheMars](https://github.com/ComeFromTheMars)** — Shift+Up/Down transcript scroll shortcuts (#1432)
-- **[sockerch](https://github.com/sockerch)** — pinyin aliases for all slash commands (#1306)
-- **[Apeiron0w0](https://github.com/Apeiron0w0)** — FocusGained debounce for Tabby terminal flicker loop (#1560)
-- **[greyfreedom](https://github.com/greyfreedom)** — jump-to-latest-transcript button (#969)
-- **[SamhandsomeLee](https://github.com/SamhandsomeLee)** — explicit hidden-file mention completion (#1270)
-- **[dst1213](https://github.com/dst1213)** — quota-error HTTP 400 retry (#1203)
-- **[fuleinist](https://github.com/fuleinist)** — `--yolo` flag forwarding from CLI to TUI (#1233)
-- **[heloanc](https://github.com/heloanc)** — Home/End key composer support (#1246)
-- **[jinpengxuan](https://github.com/jinpengxuan)** — active provider credential preservation during onboarding (#1265)
-- **[lixiasky-back](https://github.com/lixiasky-back)** — verified npm binary adoption (#1339)
-- **[J3y0r](https://github.com/J3y0r)** — workspace-switch command (#1065)
-- **[KhalidAlnujaidi](https://github.com/KhalidAlnujaidi)** — delegate skill bundling (#1144)
-- **[Wenjunyun123](https://github.com/Wenjunyun123)** — docs anchor-offset preservation (#1282)
-- **[whtis](https://github.com/whtis)** — zh-CN README dispatcher-path sync (#1235)
-- **[aqilaziz](https://github.com/aqilaziz)** — memory skill-link fix (#1095)
-- **[wuwuzhijing](https://github.com/wuwuzhijing)** — rsproxy rustup workaround install docs (#1011)
-- **[eltociear](https://github.com/eltociear)** — Japanese README translation (#746)
-- **[Ling](https://github.com/LING71671)** — `grep_files` cancellation-token support and Ctrl+Z composer-draft recovery (#1839, #1911)
-- **[Ben Younes](https://github.com/ousamabenyounes)** — Linux Wayland (non-wlroots) clipboard support (#1938)
-- **[Matt Van Horn](https://github.com/mvanhorn)** — Docker first-run permission fix and runtime system-prompt regression tests (#1699, #1702)
-- **[Kristopher Clark](https://github.com/krisclarkdev)** — compaction user-query preservation fix (#1704)
-- **[tdccccc](https://github.com/tdccccc)** — composer scroll fix and pager mouse-wheel support (#1715, #1716)
-- **[LittleBlacky](https://github.com/LittleBlacky)** — provider-gated `reasoning_content` stream fix (#1680)
-- **[Anaheim](https://github.com/AnaheimEX)** — `rlm_open` blank-source schema validation report (#1712)
-- **[THatch26](https://github.com/THatch26)** — terminal resize paging fix (#1724)
-- **[Alvin](https://github.com/alvin1)** — Zed ACP id compatibility report (#1696)
-- **[knqiufan](https://github.com/knqiufan)** — sub-agent file-write delegation work (#1833)
-- **[IIzzaya](https://github.com/IIzzaya)** — exact-alias-first slash-completion ordering idea (#1811)
-- **[DC](https://github.com/duanchao-lab)** — terminal cleanup-guard idea (#1630)
-- **[imkingjh999](https://github.com/imkingjh999)** — provider/model switching fixes (#1642)
-- **[Photo](https://github.com/eng2007)** — provider-aware `/model` picker catalog work (#1201)
-- **[chennest](https://github.com/chennest)** — diagnostics schema report (#1685)
-- **[kunpeng-ai-lab](https://github.com/kunpeng-ai-lab)** — Windows composer scroll fix (#1578)
-- **[WuMing](https://github.com/asdfg314284230)** — Windows PowerShell flicker fix (#1591)
-- **[maker316](https://github.com/maker316)** — LoopGuard/checklist loop report (#1574)
-- **[lalala](https://github.com/lalala-233)** — approval denial regression report (#1617)
-- **[muyuliyan](https://github.com/muyuliyan)** — `pandoc_convert` validation fix (#1523)
-- **[czf0718](https://github.com/czf0718)** — resize and turn-completion flicker fix (#1537)
-- **[MeAiRobot](https://github.com/MeAiRobot)** — toast overlay composer-input fix (#1485)
-- **[tiger-dog](https://github.com/tiger-dog)** — approval modal collapse and markdown identifier fixes (#1455)
-- **[MMMarcinho](https://github.com/MMMarcinho)** — opt-in `image_analyze` vision tool (#1467)
-- **[lucaszhu-hue](https://github.com/lucaszhu-hue)** — AtlasCloud provider integration (#1436)
-- **[sandofree](https://github.com/sandofree)** — Tavily and Bocha `web_search` backends (#1294)
-- **[zhuangbiaowei](https://github.com/zhuangbiaowei)** — `/change` release-notes command (#1416)
-- **[NorethSea](https://github.com/NorethSea)** — updater companion-binary refresh fix (#1492)
-- **[Jianfengwu2024](https://github.com/Jianfengwu2024)** — Windows MSVC toolchain environment preservation (#1487)
-- **[Fire-dtx](https://github.com/Fire-dtx)** — npm postinstall recoverability work (#1059)
-- **[oooyuy92](https://github.com/oooyuy92)** — long-session palette readability report (#1070, #936)
-- **[qinxianyuzou](https://github.com/qinxianyuzou)** — zh-Hans destructive approval wording (#1087, #1091)
-- **[tyouter](https://github.com/tyouter)** — session title/history preview cleanup (#1510)
-- **[xulongzhe](https://github.com/xulongzhe)** — issue-template and vision-boundary follow-ups (#1530, #1544)
-- **[YaYII](https://github.com/YaYII)** — trusted media path work (#1462)
-- **[47Cid](https://github.com/47Cid)** and **[Jafar Akhondali](https://github.com/JafarAkhondali)** — responsible security disclosures and hardening reports
+- **[donglovejava](https://github.com/donglovejava)** — paste @file consolidation, CJK panic fix, user feedback, RLM routing, edit_file retry (#2154–#2168)
+- **[encyc](https://github.com/encyc)** — session token breakdown in footer and `/status` (#2152)
+- **[saieswar237](https://github.com/saieswar237)** — review pipeline docs (#2178)
+- **[sximelon](https://github.com/sximelon)** — paste Enter suppression, key handler extraction (#2174, #2042)
+- **[nanookclaw](https://github.com/nanookclaw)** — search provider in doctor output (#2135)
+- **[Sskift](https://github.com/Sskift)** — CLI default env override prevention (#2119)
+- **[xin1104](https://github.com/xin1104)** — Homebrew codewhale binary install (#2105)
+- **[mrluanma](https://github.com/mrluanma)** — Metaso search provider (#2059)
+- **[Lellansin](https://github.com/Lellansin)** — skip config merge at home dir (#2055)
+- **[zhuangbiaowei](https://github.com/zhuangbiaowei)** — update release channels (#2145)
 
 ---
 
@@ -714,10 +677,7 @@ This project ships with help from a growing community of contributors:
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests welcome — check the [open issues](https://github.com/Hmbown/CodeWhale/issues) for good first contributions.
 
-If you want CodeWhale to help improve CodeWhale, start with the
-[recursive self-improvement prompt](docs/RECURSIVE_SELF_IMPROVEMENT.md). It is
-designed to turn one DeepSeek V4 Pro session, or another capable open-weight
-path, into one small, reviewable patch.
+Support: [Buy me a coffee](https://www.buymeacoffee.com/hmbown).
 
 > [!Note]
 > *Not affiliated with DeepSeek Inc.*
diff --git a/README.vi.md b/README.vi.md
new file mode 100644
index 00000000..91f39d19
--- /dev/null
+++ b/README.vi.md
@@ -0,0 +1,593 @@
+# 🐳 CodeWhale
+
+> **Agent lập trình gốc terminal dành cho DeepSeek V4. Chương trình chạy từ lệnh `codewhale`, hỗ trợ stream các khối suy nghĩ (reasoning blocks), chỉnh sửa workspace cục bộ thông qua các lớp phê duyệt, và đi kèm chế độ tự động để tự chọn mô hình cũng như mức độ suy nghĩ phù hợp cho mỗi lượt.**
+
+[English README](README.md)
+[简体中文 README](README.zh-CN.md)
+[日本語 README](README.ja-JP.md)
+
+## Cài đặt
+
+`codewhale` được cài đặt dưới dạng một cặp binary tự chạy bằng Rust đồng bộ với nhau:
+Lệnh điều phối `codewhale` (dispatcher) và môi trường chạy giao diện `codewhale-tui` (runtime) do nó khởi chạy để thực hiện các phiên làm việc tương tác. Các trình quản lý gói như npm, Homebrew, và Docker sẽ tự động cài đặt cả hai cho bạn; đối với Cargo hoặc cài đặt thủ công, bạn phải đặt cả hai tệp binary này trong cùng một thư mục (thông thường là một thư mục nằm trong biến môi trường `PATH` của bạn). Gói npm chỉ là một trình cài đặt/bao bọc (wrapper) cho các tệp binary phát hành này; agent không chạy trên môi trường Node.js.
+
+```bash
+# 1. npm — dễ nhất nếu bạn đã cài đặt Node. Gói này sẽ tự động tải các
+#    binary Rust dựng sẵn tương ứng từ GitHub Releases.
+npm install -g codewhale
+
+# 2. Cargo — không cần Node. Yêu cầu phiên bản Rust từ 1.88 trở lên (các crate sử dụng
+#    phiên bản Rust edition 2024; các toolchain cũ hơn sẽ báo lỗi "feature `edition2024` is
+#    required"). Hãy chạy lệnh `rustup update` trước, hoặc sử dụng các cách cài đặt không qua Cargo ở dưới.
+cargo install codewhale-cli --locked   # cài đặt `codewhale` (điểm truy cập CLI chính)
+cargo install codewhale-tui     --locked   # cài đặt `codewhale-tui` (giao diện TUI)
+
+# 3. Homebrew — trình quản lý gói dành cho macOS.
+#    Tên tap/formula là tên cũ (legacy); nó sẽ cài đặt cả codewhale và codewhale-tui.
+brew tap Hmbown/deepseek-tui
+brew install deepseek-tui
+
+# 4. Tải xuống trực tiếp — các gói lưu trữ theo nền tảng từ GitHub Releases.
+#    https://github.com/Hmbown/CodeWhale/releases
+#    Gói nén bao gồm cả codewhale và codewhale-tui cùng một tập lệnh cài đặt.
+#    Các binary riêng lẻ cũng được đính kèm cho các tập lệnh; hãy giữ cặp này ở cùng một nơi.
+
+# 5. Docker — hình ảnh phát hành dựng sẵn.
+docker volume create codewhale-home
+docker run --rm -it \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  -v codewhale-home:/home/codewhale/.codewhale \
+  -v "$PWD:/workspace" \
+  -w /workspace \
+  ghcr.io/hmbown/codewhale:latest
+```
+
+> Tại Trung Quốc đại lục, bạn có thể tăng tốc độ tải qua npm bằng tham số
+> `--registry=https://registry.npmmirror.com`, hoặc sử dụng
+> [Cargo mirror](#china--cai-dat-than-thien-qua-mirror) bên dưới.
+>
+> An toàn tải xuống: Các binary phát hành chính thức chỉ nằm tại
+> `https://github.com/Hmbown/CodeWhale/releases`. Nếu tải thủ công,
+> vui lòng xác minh mã băm SHA-256 manifest và tránh các kho lưu trữ giả mạo hoặc các
+> trang web mirror trên kết quả tìm kiếm. Xem [an toàn tải xuống và mã xác thực](docs/INSTALL.md#2-download-safety-and-checksums).
+
+Đã cài đặt từ trước? Sử dụng lệnh cập nhật tương ứng với cách bạn đã cài đặt:
+
+```bash
+codewhale update                         # trình cập nhật binary phát hành trực tiếp
+npm install -g codewhale@latest      # thông qua trình bao bọc npm
+brew update && brew upgrade deepseek-tui
+cargo install codewhale-cli --locked --force
+cargo install codewhale-tui     --locked --force
+```
+
+[![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale)
+[![crates.io](https://img.shields.io/crates/v/codewhale-cli?label=crates.io)](https://crates.io/crates/codewhale-cli)
+[Mục lục dự án DeepWiki](https://deepwiki.com/Hmbown/CodeWhale)
+
+![ảnh chụp màn hình codewhale](assets/screenshot.png)
+
+---
+
+## CodeWhale là gì?
+
+Mô hình AI chỉ trả lời câu hỏi. Agent hoàn thành một nhiệm vụ. Sự khác biệt nằm ở
+**khung ràng buộc (harness)** — một hệ thống các quy tắc, bằng chứng và phản hồi giúp giữ cho
+mô hình đi đúng hướng thay vì bị trôi lệch mục tiêu.
+
+CodeWhale chính là khung ràng buộc đó, được xây dựng xung quanh DeepSeek V4 và được dẫn dắt bởi ba ý tưởng chính:
+
+| Nguyên tắc | Cách thức hoạt động |
+|---|---|
+| **Bắt đầu với sự tin tưởng** | Mỗi lượt bắt đầu bằng chữ "A" — tìm kiếm khả năng trước khi khẳng định chắc chắn, chú trọng chất lượng trước sự tiện lợi |
+| **Thẩm quyền rõ ràng** | Một bản Hiến pháp bằng văn bản với chín cấp bậc thẩm quyền. Ý định của người dùng quan trọng hơn các hướng dẫn cũ kỹ. Sự xác minh quan trọng hơn sự tự tin. |
+| **Cải tiến đệ quy** | V4 đã tham gia viết nên một phần của khung ràng buộc này. Khi khung ràng buộc tốt lên, V4 hoạt động hiệu quả hơn — và giúp cải tiến khung ràng buộc hơn nữa. Mỗi lượt chạy mới đều bắt đầu mạnh mẽ hơn. |
+
+Dự án này là mã nguồn mở, hoạt động trực tiếp trên terminal và được đóng gói thành một cặp binary Rust đồng bộ là `codewhale` / `codewhale-tui`.
+
+## Khung Ràng Buộc Hoạt Động Thế Nào?
+
+Các mô hình dạng Agent phải xử lý lượng thông tin xung đột rất lớn trên quy mô lớn: ý định của người dùng, quy tắc dự án, cấu hình mặc định của hệ thống, đầu ra của công cụ và bộ nhớ cũ đều cạnh tranh thẩm quyền trong một lượt chạy duy nhất. LLM hoạt động như một thẩm phán cần có thẩm quyền rõ ràng — nguồn thông tin nào sẽ thắng thế khi xảy ra xung đột?
+
+CodeWhale giải quyết vấn đề này bằng một bản **Hiến pháp** (`prompts/base.md`). Đây là một hệ thống phân cấp luật chính thức — Điều VII xếp hạng chín nguồn thông tin từ các điều khoản của chính Hiến pháp xuống đến thông tin bàn giao từ phiên làm việc trước. Tin nhắn hiện tại của người dùng có thẩm quyền cao hơn các hướng dẫn dự án cũ kỹ. Đầu ra trực tiếp từ công cụ có thẩm quyền cao hơn các giả định. Việc xác minh thực tế có thẩm quyền cao hơn sự tự tin của mô hình. Mô hình kế thừa một chuỗi thẩm quyền rõ ràng qua từng lượt và không bao giờ phải đoán xem nên làm theo chỉ thị nào.
+
+Có bảy điều khoản đứng đầu hệ thống phân cấp này, định nghĩa danh tính, nghĩa vụ và quyền hạn của mô hình: yêu cầu xác minh (Điều V — mọi hành động phải để lại bằng chứng thực tế, không bao giờ tuyên bố thành công dựa trên niềm tin mơ hồ), di sản điều phối (Điều VI — giữ cho workspace dễ đọc để trí tuệ tiếp theo có thể tiếp quản), và điều khoản ưu tiên sự thật (Điều II — không có quy tắc cấp dưới nào được phép ghi đè lên nó).
+
+Bộ nhớ đệm tiền tố (prefix caching) của DeepSeek V4 làm cho điều này trở nên khả thi và thực tế. Bản Hiến pháp rất dài và chi tiết, nhưng một khi đã được cache, nó sẽ tốn ít hơn khoảng 100 lần chi phí cho mỗi lượt so với một lần đọc mới hoàn toàn. Mô hình tham chiếu nó một cách đệ quy — xem qua, quét và truy vấn thông qua các phiên RLM — truy cập lại thông tin theo nhu cầu thay vì chỉ dựa trên một lượt ghi nhớ duy nhất. Nó hoạt động giống như một bài kiểm tra mở sách hơn là kiểm tra đóng sách.
+
+Bởi vì cấu trúc thẩm quyền là tường minh, các lỗi và thất bại không bao giờ bị che giấu. Các mã thoát (exit codes) khác không, lỗi kiểu dữ liệu từ rust-analyzer trả về giữa các lượt, từ chối của sandbox — tất cả đều được đưa ngược lại như các vectơ sửa lỗi. Mô hình sử dụng chính sự chệch hướng của mình để tự sửa sai.
+
+Ba chế độ kiểm soát không gian hành động: **Plan** là chế độ chỉ đọc. **Agent** chặn các thao tác can thiệp thay đổi file đằng sau quyền phê duyệt của người dùng. **YOLO** tự động phê duyệt tất cả các công cụ trong các workspace đáng tin cậy. Chế độ Sandbox hoạt động trên macOS Seatbelt; Linux Landlock đã được phát hiện nhưng chưa được áp dụng bắt buộc; chế độ sandboxing trên Windows hiện chưa được hỗ trợ.
+
+**Fin** — một cuộc gọi Flash giá rẻ và tắt chức năng suy nghĩ — xử lý việc tự động định tuyến mô hình cho mỗi lượt. Tham số mặc định là `--model auto`.
+
+Mỗi lượt chạy đều ghi lại một ảnh chụp nhanh side-git bên ngoài thư mục `.git` của repo. Các lệnh `/restore` và `revert_turn` giúp khôi phục nhanh workspace về trạng thái trước đó.
+
+Các sub-agent chạy đồng thời (tối đa 20). Lệnh `agent_open` trả về kết quả ngay lập tức; kết quả trả về nội tuyến dưới dạng các sentinel hoàn thành kèm theo bản tóm tắt. Nhật ký chi tiết của sub-agent được lưu trữ và truy cập thông qua `agent_eval`. Xem chi tiết tại [docs/SUBAGENTS.md](docs/SUBAGENTS.md).
+
+Các tính năng khác của hệ thống bao gồm: chẩn đoán lỗi LSP sau mỗi lần chỉnh sửa file (rust-analyzer, pyright, typescript-language-server, gopls, clangd), các phiên làm việc RLM để phân tích hàng loạt, giao thức MCP, API runtime HTTP/SSE, hàng đợi tác vụ liên tục, adapter ACP cho trình soạn thảo Zed, xuất kết quả định dạng SWE-bench và theo dõi chi phí trực tiếp với bảng phân tích chi tiết lượt hit/miss cache.
+
+---
+
+## Khung Kết Nối (Harness)
+
+`codewhale` (CLI điều phối) → `codewhale-tui` (binary giao diện) → giao diện ratatui ↔ công cụ bất đồng bộ ↔ máy khách streaming tương thích với OpenAI. Các lượt gọi công cụ được định tuyến qua một registry có phân loại (shell, thao tác file, git, web, sub-agent, MCP, RLM) và kết quả được truyền trực tuyến trở lại transcript. Công cụ quản lý trạng thái phiên làm việc, theo dõi lượt chạy, hàng đợi tác vụ bền bỉ và một phân hệ LSP cung cấp thông tin chẩn đoán sau khi chỉnh sửa vào ngữ cảnh của mô hình trước bước suy nghĩ tiếp theo.
+
+Xem tài liệu [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) để biết chi tiết toàn bộ luồng hoạt động.
+
+### Sub-agents: Khởi chạy Tác vụ Nền Đồng thời
+
+CodeWhale có thể điều phối nhiều sub-agent chạy song song — hoạt động giống như một hàng đợi tác vụ đồng thời:
+
+- **Khởi chạy không chặn:** Lệnh `agent_open` trả về ngay lập tức. Sub-agent con có một ngữ cảnh độc lập mới và hệ thống đăng ký công cụ riêng để chạy tự chủ. Agent cha vẫn tiếp tục làm việc bình thường.
+- **Thực thi dưới nền:** Các sub-agent chạy đồng thời (giới hạn mặc định: 10, có thể cấu hình lên đến 20). Hệ thống tự quản lý pool tài nguyên này mà không cần vòng lặp thăm dò (polling loop).
+- **Thông báo hoàn thành:** Khi một sub-agent hoàn thành, hệ thống sẽ chèn một khóa sentinel `<codewhale:subagent.done>` vào transcript của agent cha. Một bản tóm tắt thân thiện với con người — bao gồm phát hiện của sub-agent con, các file đã thay đổi và các rủi ro có thể xảy ra — nằm ngay dòng phía trên khóa sentinel. Mô hình cha sẽ đọc tóm tắt đó và tích hợp kết quả thu được mà không cần phải thực hiện thêm bất kỳ lệnh gọi công cụ nào khác.
+- **Truy xuất kết quả có giới hạn:** Nhật ký chi tiết của agent con nằm dưới dạng một `transcript_handle` có thể truy cập qua `agent_eval`. Khi bản tóm tắt là chưa đủ, agent cha có thể gọi `handle_read` để đọc một phần, các dòng cụ thể hoặc lọc qua JSONPath — giúp ngữ cảnh của agent cha luôn tinh gọn mà không làm mất đi các chi tiết quan trọng.
+
+Xem thêm tài liệu [docs/SUBAGENTS.md](docs/SUBAGENTS.md) để tham khảo thông tin đầy đủ về sub-agent.
+
+---
+
+## Khởi động nhanh
+
+```bash
+npm install -g codewhale
+codewhale --version
+codewhale --model auto
+```
+
+Cặp binary dựng sẵn và gói nén nền tảng được phát hành cho các kiến trúc **Linux x64**, **Linux ARM64** (từ v0.8.8 trở lên), **macOS x64**, **macOS ARM64**, và **Windows x64**. Đối với các mục tiêu khác (musl, riscv64, FreeBSD, v.v.), xem phần [Cài đặt từ nguồn](#install-from-source) hoặc tài liệu [docs/INSTALL.md](docs/INSTALL.md).
+
+Trong lần chạy đầu tiên, bạn sẽ được nhắc nhập [API key của DeepSeek](https://platform.deepseek.com/api_keys). Khóa này được lưu vào tệp cấu hình `~/.codewhale/config.toml` (tương thích cả tệp cũ `~/.deepseek/config.toml`) để nó hoạt động từ bất kỳ thư mục nào mà không cần nhắc thông tin đăng nhập của hệ điều hành.
+
+Bạn cũng có thể thiết lập trước:
+
+```bash
+codewhale auth set --provider deepseek   # lưu vào ~/.codewhale/config.toml
+codewhale auth status                    # hiển thị nguồn thông tin đăng nhập đang hoạt động
+
+export DEEPSEEK_API_KEY="YOUR_KEY"      # cách thiết lập qua biến môi trường thay thế; sử dụng ~/.zshenv cho terminal không tương tác
+codewhale
+
+codewhale doctor                         # kiểm tra và xác minh thiết lập
+```
+
+Nếu lệnh `codewhale doctor` báo lỗi API key bị từ chối đến từ biến môi trường `DEEPSEEK_API_KEY`, hãy xóa cấu hình xuất biến môi trường cũ trong tệp khởi chạy shell của bạn, mở một shell mới hoặc chạy lệnh `codewhale auth set --provider deepseek`. Sử dụng `codewhale auth status` để xem trạng thái của cấu hình, keyring hệ thống và biến môi trường mà không hiển thị trực tiếp khóa API. Các khóa lưu trong file cấu hình sẽ được ưu tiên cao hơn keyring và môi trường để dễ dàng thay đổi khi cần.
+
+> Để thay đổi hoặc xóa khóa đã lưu: `codewhale auth clear --provider deepseek`.
+
+### Tencent Cloud / CNB Remote-First Path
+
+Đối với không gian làm việc luôn trực tuyến mà bạn có thể điều khiển từ điện thoại, hãy sử dụng đường dẫn gốc của Tencent: CNB mirror/source, Tencent Lighthouse HK, cầu kết nối dài hạn Feishu/Lark, và EdgeOne tùy chọn cho một cổng HTTPS công cộng có kiểm soát. API runtime luôn được giới hạn chạy tại localhost; EdgeOne không được sử dụng để hiển thị công khai đường dẫn `/v1/*`.
+
+Bắt đầu với tài liệu [docs/TENCENT_CLOUD_REMOTE_FIRST.md](docs/TENCENT_CLOUD_REMOTE_FIRST.md), sau đó xem thêm tài liệu [docs/TENCENT_LIGHTHOUSE_HK.md](docs/TENCENT_LIGHTHOUSE_HK.md) để biết các vận hành máy chủ.
+
+### Chế độ Tự động (Auto Mode)
+
+Sử dụng `codewhale --model auto` hoặc gõ lệnh `/model auto` khi bạn muốn hệ thống tự động quyết định sức mạnh của mô hình và cấp độ suy nghĩ cần thiết cho mỗi lượt.
+
+Chế độ tự động điều khiển hai cài đặt cùng nhau:
+
+- Mô hình: `deepseek-v4-flash` hoặc `deepseek-v4-pro`
+- Cấp độ suy nghĩ: `off`, `high`, hoặc `max`
+
+Trước khi lượt gửi chính thức được thực hiện, ứng dụng sẽ thực hiện một cuộc gọi định tuyến nhỏ thông qua mô hình `deepseek-v4-flash` tắt chế độ suy nghĩ. Trình định tuyến đó sẽ đánh giá yêu cầu mới nhất và ngữ cảnh gần đây, từ đó chọn mô hình cụ thể và cấp độ suy nghĩ phù hợp cho lượt gọi thực tế. Các lượt tương tác ngắn/đơn giản sẽ được chạy trên mô hình Flash tắt suy nghĩ; các công việc lập trình phức tạp, gỡ lỗi, phát hành, kiến trúc phần mềm, kiểm tra bảo mật hoặc các tác vụ nhiều bước mơ hồ sẽ được đẩy lên mô hình Pro với cấp độ suy nghĩ cao hơn.
+
+Cơ chế `auto` hoạt động hoàn toàn cục bộ trên máy của bạn. API ở máy chủ upstream không bao giờ nhận được chuỗi `model: "auto"`; nó luôn nhận được mô hình cụ thể và cấu hình suy nghĩ đã được chọn cho lượt chạy đó. Giao diện TUI hiển thị tuyến đường định tuyến được chọn và bộ theo dõi chi phí sẽ tính tiền cho mô hình thực tế đã chạy. Nếu cuộc gọi định tuyến thất bại hoặc trả về câu trả lời không hợp lệ, ứng dụng sẽ chuyển sang thuật toán phỏng đoán cục bộ. Các sub-agent con sẽ kế thừa chế độ tự động này trừ khi bạn chỉ định rõ một mô hình cho chúng.
+
+Hãy chỉ định mô hình hoặc cấp độ suy nghĩ cố định nếu bạn muốn chạy benchmark lặp lại nhất quán, kiểm soát nghiêm ngặt chi phí trần hoặc có cấu hình ánh xạ nhà cung cấp/mô hình tùy chỉnh cụ thể.
+
+### Linux ARM64 (Raspberry Pi, Asahi, Graviton, HarmonyOS PC)
+
+Lệnh cài đặt `npm i -g codewhale` hoạt động trên môi trường Linux ARM64 nền glibc từ phiên bản v0.8.8 trở đi. Bạn cũng có thể tải trực tiếp các tệp binary dựng sẵn từ [trang phát hành Releases](https://github.com/Hmbown/CodeWhale/releases) và đặt chúng cạnh nhau trong một thư mục thuộc biến `PATH`.
+
+### Cài đặt thân thiện qua Mirror (Tại Trung Quốc)
+
+Nếu việc tải xuống từ GitHub hoặc npm bị chậm từ Trung Quốc đại lục, bạn hãy sử dụng mirror registry cho Cargo:
+
+```toml
+# ~/.cargo/config.toml
+[source.crates-io]
+replace-with = "tuna"
+
+[source.tuna]
+registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
+```
+
+Sau đó cài đặt cả hai binary (trình điều phối sẽ ủy quyền cho TUI tại thời điểm chạy):
+
+```bash
+cargo install codewhale-cli --locked   # cung cấp lệnh `codewhale`
+cargo install codewhale-tui     --locked   # cung cấp giao diện `codewhale-tui`
+codewhale --version
+```
+
+Các binary dựng sẵn cũng có thể được tải từ [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases). Thiết lập biến `DEEPSEEK_TUI_RELEASE_BASE_URL` để sử dụng mirror tải các tệp tài nguyên phát hành.
+
+### Windows (Scoop)
+
+[Scoop](https://scoop.sh) là một trình quản lý gói phổ biến trên Windows. Gói `codewhale` đã được liệt kê trong bucket chính của Scoop, tuy nhiên gói cài đặt này hoạt động độc lập và đôi khi cập nhật chậm hơn các bản phát hành chính thức trên GitHub/npm/Cargo. Chạy lệnh `scoop update` trước, sau đó xác minh phiên bản đã cài bằng `codewhale --version`:
+
+```bash
+scoop update
+scoop install codewhale
+codewhale --version
+```
+
+Vui lòng sử dụng phương pháp npm hoặc tải trực tiếp từ GitHub Releases nếu bạn muốn trải nghiệm phiên bản mới nhất trước khi Scoop cập nhật.
+
+<details id="install-from-source">
+<summary>Cài đặt từ mã nguồn</summary>
+
+Cách này hoạt động trên bất kỳ kiến trúc mục tiêu Tier-1 nào được Rust hỗ trợ — bao gồm cả musl, riscv64, FreeBSD và các bản phân phối ARM64 Linux cũ.
+
+```bash
+# Các thư viện phụ thuộc để build trên Linux (Debian/Ubuntu/RHEL):
+#   sudo apt-get install -y build-essential pkg-config libdbus-1-dev
+#   sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
+
+git clone https://github.com/Hmbown/CodeWhale.git
+cd CodeWhale
+
+cargo install --path crates/cli --locked   # yêu cầu Rust 1.88+; cung cấp `codewhale`
+cargo install --path crates/tui --locked   # cung cấp giao diện `codewhale-tui`
+```
+
+Cả hai tệp binary đều bắt buộc phải cài đặt. Xem hướng dẫn biên dịch chéo và ghi chú riêng theo nền tảng tại: [docs/INSTALL.md](docs/INSTALL.md).
+
+</details>
+
+### Các Nhà Cung Cấp API Khác
+
+Để xem danh sách đầy đủ tất cả các nhà cung cấp được hỗ trợ chính thức, bao gồm mã định danh mô hình, biến xác thực, URL cơ sở và ranh giới tính năng, xem thêm tài liệu [docs/PROVIDERS.md](docs/PROVIDERS.md).
+
+```bash
+# NVIDIA NIM
+codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"
+codewhale --provider nvidia-nim
+
+# AtlasCloud
+codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"
+codewhale --provider atlascloud
+
+# Wanjie Ark
+codewhale auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"
+codewhale --provider wanjie-ark --model deepseek-reasoner
+
+# OpenRouter
+codewhale auth set --provider openrouter --api-key "YOUR_OPENROUTER_API_KEY"
+codewhale --provider openrouter --model deepseek/deepseek-v4-pro
+
+# Novita
+codewhale auth set --provider novita --api-key "YOUR_NOVITA_API_KEY"
+codewhale --provider novita --model deepseek/deepseek-v4-pro
+
+# Fireworks
+codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"
+codewhale --provider fireworks --model deepseek-v4-pro
+
+# Các endpoint tương thích định dạng OpenAI chung
+codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"
+OPENAI_BASE_URL="https://openai-compatible.example/v4" codewhale --provider openai --model glm-5
+
+# Tự host bằng SGLang
+SGLANG_BASE_URL="http://localhost:30000/v1" codewhale --provider sglang --model deepseek-v4-flash
+
+# Tự host bằng vLLM
+VLLM_BASE_URL="http://localhost:8000/v1" codewhale --provider vllm --model deepseek-v4-flash
+# Sử dụng vLLM qua kết nối HTTP trong mạng LAN đáng tin cậy
+DEEPSEEK_ALLOW_INSECURE_HTTP=1 VLLM_BASE_URL="http://192.168.0.110:8000/v1" codewhale --provider vllm --model deepseek-v4-flash
+
+# Tự host bằng Ollama
+ollama pull codewhale-coder:1.3b
+codewhale --provider ollama --model codewhale-coder:1.3b
+```
+
+Bên trong giao diện TUI, lệnh `/provider` mở bảng chọn nhà cung cấp và `/model` mở bảng chọn mô hình/cấp độ suy nghĩ cục bộ. Lệnh `/provider openrouter` và `/model <id>` chuyển đổi trực tiếp, trong khi lệnh `/models` sẽ truy vấn trực tiếp và hiển thị danh sách các mô hình API trực tuyến từ nhà cung cấp (nếu nhà cung cấp hỗ trợ tính năng liệt kê mô hình).
+
+---
+
+## Nhật ký thay đổi (Release Notes)
+
+Chi tiết thay đổi giữa các phiên bản được cập nhật tại [CHANGELOG.md](CHANGELOG.md). File README này chỉ tập trung vào các đường dẫn cài đặt hiện tại, quy trình làm việc cốt lõi, thiết lập nhà cung cấp API, giao diện và các điểm mở rộng tính năng của dự án.
+
+---
+
+## Cách sử dụng
+
+```bash
+codewhale                                         # giao diện tương tác TUI chính
+codewhale "explain this function"                 # thực thi prompt nhanh một lượt
+codewhale exec --auto --output-format stream-json "fix this bug"  # truyền phát luồng dữ liệu NDJSON backend
+codewhale exec --resume <SESSION_ID> "follow up"  # tiếp tục phiên làm việc không tương tác cũ
+codewhale --model deepseek-v4-flash "summarize"   # ghi đè mô hình chạy chỉ định
+codewhale --model auto "fix this bug"             # tự động chọn mô hình và cấp độ suy nghĩ thích hợp
+codewhale --yolo                                  # tự động phê duyệt chạy các công cụ
+codewhale auth set --provider deepseek            # lưu trữ API key
+codewhale doctor                                  # tự động kiểm tra cài đặt và kết nối mạng
+codewhale doctor --json                           # trả về chuẩn đoán định dạng máy đọc được
+codewhale setup --status                          # chỉ đọc trạng thái thiết lập hiện tại
+codewhale setup --tools --plugins                 # tạo sẵn cấu trúc thư mục tool/plugin
+codewhale models                                  # liệt kê các mô hình khả dụng trực tuyến
+codewhale sessions                                # liệt kê các phiên làm việc đã lưu
+codewhale resume --last                           # tiếp tục phiên làm việc gần nhất trong thư mục này
+codewhale resume <SESSION_ID>                     # tiếp tục một phiên làm việc cụ thể theo mã UUID
+codewhale fork <SESSION_ID>                       # tạo một nhánh (fork) phiên làm việc đã lưu sang đường dẫn mới
+codewhale serve --http                            # khởi chạy máy chủ API định dạng HTTP/SSE
+codewhale serve --acp                             # khởi chạy adapter ACP qua stdio cho trình soạn thảo Zed/agent tùy chỉnh
+codewhale run pr <N>                              # tải PR về và nạp sẵn vào prompt đánh giá
+codewhale mcp list                                # liệt kê các máy chủ MCP đã cấu hình
+codewhale mcp validate                            # kiểm tra cấu hình và kết nối máy chủ MCP
+codewhale mcp-server                              # khởi chạy máy chủ MCP điều phối qua cổng stdio
+codewhale update                                  # kiểm tra và cài đặt phiên bản binary mới nhất
+```
+
+### Tạo nhánh phiên làm việc (Branching)
+
+Các phiên làm việc được lưu có thể được phân nhánh một cách có chủ đích. Lệnh `codewhale fork <SESSION_ID>` sao chép toàn bộ phiên làm việc cũ sang một phiên mới song song, lưu trữ mã ID của phiên cha trong siêu dữ liệu (metadata) và mở phiên fork đó ra để bạn có thể thử nghiệm hướng phát triển mới mà không làm ảnh hưởng đến lịch sử phiên làm việc gốc. Trình chọn phiên làm việc và danh sách `codewhale sessions` sẽ đánh dấu rõ ràng các phiên được fork kèm theo mã ID của phiên cha.
+
+Bên trong giao diện TUI, bạn có thể nhấn phím `Esc` hai lần (`Esc-Esc`) để quay ngược lại transcript và đưa prompt cũ về lại phần soạn thảo để chỉnh sửa lại nội dung. Các lệnh `/restore` và `revert_turn` là công cụ khôi phục workspace độc lập: chúng khôi phục lại các tệp tin dựa trên ảnh chụp nhanh side-git nhưng không làm thay đổi hay ghi đè lịch sử trò chuyện của phiên làm việc.
+
+Các hình ảnh Docker được phát hành lên GHCR cho các bản dựng phát hành chính thức:
+
+```bash
+docker volume create codewhale-home
+
+docker run --rm -it \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  -v codewhale-home:/home/codewhale/.codewhale \
+  -v "$PWD:/workspace" \
+  -w /workspace \
+  ghcr.io/hmbown/codewhale:latest
+```
+
+Xem tài liệu [docs/DOCKER.md](docs/DOCKER.md) để biết thêm thông tin về thẻ phiên bản (pinned tags), cách tự dựng image cục bộ, lưu ý quyền sở hữu volume và cách sử dụng cho pipeline không tương tác.
+
+### Zed / ACP
+
+DeepSeek có thể chạy dưới dạng một máy chủ Agent Client Protocol (ACP) cục bộ cho các trình soạn thảo mã nguồn hỗ trợ giao tiếp ACP qua cổng stdio. Trong trình soạn thảo Zed, bạn hãy thêm cấu hình máy chủ agent tùy chỉnh sau:
+
+```json
+{
+  "agent_servers": {
+    "DeepSeek": {
+      "type": "custom",
+      "command": "codewhale",
+      "args": ["serve", "--acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Phân hệ ACP ban đầu hỗ trợ khởi tạo phiên làm việc mới và nhận phản hồi prompt qua cấu hình và API key hiện tại của DeepSeek. Tính năng chỉnh sửa tích hợp công cụ và phát lại checkpoint hiện chưa được hỗ trợ qua giao diện ACP.
+
+Adapter do cộng đồng phát triển: [acp-codewhale-adapter](https://github.com/rockeverm3m/acp-codewhale-adapter) hỗ trợ cầu nối lệnh `codewhale exec --auto` với `cc-connect` cho người dùng cần quy trình làm việc ACP có tích hợp công cụ bên ngoài trình soạn thảo Zed.
+
+### Phím Tắt Tiêu Biểu
+
+| Phím | Hành động |
+|---|---|
+| `Tab` | Hoàn thành gợi ý lệnh `/` hoặc các nhãn tệp `@`; khi đang chạy, xếp tin nhắn nháp vào hàng đợi chạy tiếp theo; hoặc chuyển đổi qua lại giữa các chế độ |
+| `Shift+Tab` | Thay đổi nhanh cấp độ suy nghĩ: off → high → max |
+| `F1` | Mở màn hình trợ giúp phím tắt có thanh tìm kiếm |
+| `Esc` | Quay lại / đóng cửa sổ popup |
+| `Ctrl+K` | Mở bảng lệnh nhanh (Command palette) |
+| `Ctrl+R` | Tiếp tục một phiên làm việc cũ |
+| `Alt+R` | Tìm kiếm lịch sử prompt cũ để khôi phục tin nháp đã xóa |
+| `Ctrl+S` | Cất tin nháp hiện tại vào bộ nhớ tạm (dùng `/stash list`, `/stash pop` để lấy lại) |
+| `@path` | Đính kèm ngữ cảnh file hoặc thư mục trực tiếp tại trình soạn thảo văn bản |
+| `↑` (tại đầu composer) | Chọn hàng tệp tin đính kèm để xóa |
+
+Xem danh sách phím tắt đầy đủ tại: [docs/KEYBINDINGS.md](docs/KEYBINDINGS.md).
+
+---
+
+## Chế độ hoạt động (Modes)
+
+| Chế độ | Hành vi hoạt động |
+| --- | --- |
+| **Plan** 🔍 | Chế độ khảo sát chỉ đọc — mô hình tìm hiểu cấu trúc và đề xuất kế hoạch hành động cụ thể trước khi sửa đổi file; các cuộc khảo sát nhiều bước sử dụng công cụ `checklist_write` |
+| **Agent** 🤖 | Chế độ tương tác mặc định — thực thi tác vụ nhiều bước có kiểm soát đằng sau các cổng phê duyệt; các tác vụ lớn sẽ được theo dõi qua `checklist_write` |
+| **YOLO** ⚡ | Tự động phê duyệt tất cả các lệnh gọi công cụ trong các workspace tin cậy; các tác vụ nhiều bước vẫn duy trì checklist hiển thị trực quan |
+
+---
+
+## Cấu hình
+
+Cấu hình của người dùng lưu tại: `~/.codewhale/config.toml` (tự động fallback về tệp cũ `~/.deepseek/config.toml` nếu có). Cấu hình riêng của dự án ghi đè tại: `<workspace>/.codewhale/config.toml` (hoặc `<workspace>/.deepseek/config.toml`) (lưu ý các trường sau bị cấm ghi đè ở cấp dự án: `api_key`, `base_url`, `provider`, `mcp_config_path`). Tham khảo tệp [config.example.toml](config.example.toml) để xem đầy đủ tất cả cấu hình mẫu.
+
+Các biến môi trường chính:
+
+| Biến môi trường | Mục đích sử dụng |
+|---|---|
+| `DEEPSEEK_API_KEY` | Khóa API key chính |
+| `DEEPSEEK_BASE_URL` | Địa chỉ URL cơ sở của máy chủ API |
+| `DEEPSEEK_HTTP_HEADERS` | Các header tùy chỉnh gửi kèm yêu cầu API, ví dụ `X-Model-Provider-Id=your-model-provider` |
+| `DEEPSEEK_MODEL` | Mô hình mặc định |
+| `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` | Thời gian chờ tối đa khi stream bị rảnh (giây), mặc định là `300`, giới hạn trong khoảng `1..=3600` |
+| `CODEWHALE_PROVIDER` / `DEEPSEEK_PROVIDER` | Các nhà cung cấp: `deepseek` (mặc định), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `novita`, `fireworks`, `moonshot`, `sglang`, `vllm`, `ollama` |
+| `DEEPSEEK_PROFILE` | Tên cấu hình profile sử dụng |
+| `DEEPSEEK_MEMORY` | Thiết lập là `on` để kích hoạt tính năng tự ghi nhớ thông tin người dùng |
+| `DEEPSEEK_ALLOW_INSECURE_HTTP=1` | Cho phép sử dụng các đường dẫn API dạng `http://` không mã hóa trong các mạng LAN tin cậy |
+| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `OPENROUTER_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `MOONSHOT_API_KEY` / `KIMI_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | Thông tin đăng nhập theo từng nhà cung cấp tương ứng |
+| `OPENAI_BASE_URL` / `OPENAI_MODEL` | Điểm cuối (endpoint) và mã mô hình cho nhà cung cấp tương thích định dạng OpenAI chung |
+| `ATLASCLOUD_BASE_URL` / `ATLASCLOUD_MODEL` | Endpoint và mô hình ghi đè cho AtlasCloud |
+| `WANJIE_ARK_BASE_URL` / `WANJIE_ARK_MODEL` | Endpoint và mô hình ghi đè cho Wanjie Ark |
+| `OPENROUTER_BASE_URL` | Endpoint ghi đè cho OpenRouter |
+| `NOVITA_BASE_URL` | Endpoint ghi đè cho Novita |
+| `FIREWORKS_BASE_URL` | Endpoint ghi đè cho Fireworks |
+| `SGLANG_BASE_URL` | Endpoint cho máy chủ SGLang tự host |
+| `SGLANG_MODEL` | Mã mô hình cho máy chủ SGLang tự host |
+| `VLLM_BASE_URL` | Endpoint cho máy chủ vLLM tự host |
+| `VLLM_MODEL` | Mã mô hình cho máy chủ vLLM tự host |
+| `OLLAMA_BASE_URL` | Endpoint cho máy chủ Ollama tự host |
+| `OLLAMA_MODEL` | Thẻ mô hình (model tag) cho máy chủ Ollama tự host |
+| `NO_ANIMATIONS=1` | Bắt buộc chạy ở chế độ hỗ trợ khả năng tiếp cận (Accessibility mode), tắt hiệu ứng khi khởi động |
+| `SSL_CERT_FILE` | Đường dẫn file CA bundle tùy chỉnh khi sử dụng proxy nội bộ doanh nghiệp |
+
+Thiết lập thuộc tính `locale` trong file `settings.toml`, sử dụng lệnh `/config locale vi`, hoặc dựa vào cài đặt biến `LC_ALL`/`LANG` của hệ điều hành để lựa chọn ngôn ngữ cho giao diện TUI và ngôn ngữ nhắc nhở gửi kèm tới các mô hình V4. Tin nhắn mới nhất của người dùng vẫn có mức độ ưu tiên cao nhất để mô hình tự động chọn ngôn ngữ phản hồi tương ứng, do đó các câu hỏi bằng Tiếng Việt của người dùng vẫn sẽ luôn nhận được câu trả lời bằng Tiếng Việt ngay cả khi hệ điều hành đang thiết lập giao diện hiển thị mặc định bằng tiếng Anh. Xem tài liệu hướng dẫn cấu hình tại [docs/CONFIGURATION.md](docs/CONFIGURATION.md) và [docs/MCP.md](docs/MCP.md).
+
+---
+
+## Mô hình & Giá cả
+
+| Mô hình | Ngữ cảnh | Đầu vào (Hit Cache) | Đầu vào (Miss Cache) | Đầu ra |
+|---|---|---|---|---|
+| `deepseek-v4-pro` | 1M | $0.003625 / 1M | $0.435 / 1M | $0.87 / 1M |
+| `deepseek-v4-flash` | 1M | $0.0028 / 1M | $0.14 / 1M | $0.28 / 1M |
+
+Nền tảng DeepSeek mặc định sử dụng đường dẫn `https://api.deepseek.com/beta` để bạn có thể trải nghiệm các tính năng API beta mà không cần thiết lập cấu hình phức tạp. Thiết lập thuộc tính `base_url = "https://api.deepseek.com"` nếu muốn tắt tính năng này.
+
+Các tên định danh cũ `deepseek-chat` / `deepseek-reasoner` sẽ được tự động ánh xạ đến `deepseek-v4-flash` và sẽ chính thức dừng hoạt động sau ngày 24 tháng 7 năm 2026. Các biến thể NVIDIA NIM sẽ áp dụng theo điều khoản tài khoản NVIDIA của bạn.
+
+> [!Note]
+> Trang cấu trúc giá của DeepSeek hiện đã cập nhật bảng giá trên của dòng V4 Pro làm mức giá cố định vĩnh viễn: Chương trình khuyến mãi giảm giá 75% trước đó đã được chính thức tích hợp thẳng vào giá cơ sở từ sau khi thời hạn khuyến mãi kết thúc vào lúc 15:59 UTC ngày 31 tháng 5 năm 2026. Trình tính toán chi phí trên giao diện TUI của CodeWhale đã cập nhật các giá trị mới này, do đó bạn không cần thực hiện thêm thay đổi nào. Để theo dõi các thay đổi giá trong tương lai, vui lòng tham khảo [trang giá chính thức của DeepSeek](https://api-docs.deepseek.com/zh-cn/quick_start/pricing).
+
+---
+
+## Chia Sẻ Skill Tự Viết
+
+CodeWhale sẽ tự động quét và tìm kiếm các skill được định nghĩa từ các thư mục của dự án (`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills` → `.cursor/skills`) và các thư mục cấu hình toàn cục (`~/.agents/skills` → `~/.claude/skills` → `~/.codewhale/skills` → `~/.deepseek/skills`). Mỗi skill là một thư mục chứa một tệp tin `SKILL.md`:
+
+```text
+~/.agents/skills/my-skill/
+└── SKILL.md
+```
+
+Yêu cầu định nghĩa phần Frontmatter ở đầu file:
+
+```markdown
+---
+name: my-skill
+description: Sử dụng skill này khi bạn muốn DeepSeek tuân thủ theo quy trình làm việc tùy chỉnh của tôi.
+---
+
+# My Skill
+Các hướng dẫn chi tiết dành cho agent được viết tại đây.
+```
+
+Các lệnh tương tác: `/skills` (liệt kê), `/skill <name>` (kích hoạt), `/skill new` (tạo khung mẫu), `/skill install github:<owner>/<repo>` (cài đặt từ cộng đồng GitHub), `/skill update` / `uninstall` / `trust` để quản lý. Cài đặt các skill từ cộng đồng GitHub không yêu cầu chạy thêm bất kỳ dịch vụ nền nào. Các skill sau khi cài đặt sẽ hiển thị trong phần ngữ cảnh phiên làm việc mà mô hình AI có thể đọc được; agent có thể tự chọn skill phù hợp qua công cụ `load_skill` khi nhiệm vụ của bạn khớp với phần mô tả của skill.
+
+Trong lần chạy đầu tiên, chương trình cũng tự động cài đặt sẵn một số skill hệ thống cho các quy trình phổ biến:
+`skill-creator`, `delegate`, `v4-best-practices`, `plugin-creator`, `skill-installer`, `mcp-builder`, `documents`, `presentations`, `spreadsheets`, `pdf`, và `feishu`. Các skill này nằm trong thư mục `~/.codewhale/skills` (hoặc thư mục cũ `~/.deepseek/skills`) và được quản lý phiên bản để các bản nâng cấp mới được cài đặt tự động mà không làm ảnh hưởng đến các skill do người dùng tự chủ động xóa trước đó.
+
+---
+
+## Tài liệu hướng dẫn
+
+| Tài liệu | Chủ đề chi tiết |
+|---|---|
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Cấu trúc bên trong của cơ sở mã nguồn |
+| [CONFIGURATION.md](docs/CONFIGURATION.md) | Hướng dẫn cấu hình chi tiết và đầy đủ nhất |
+| [MODES.md](docs/MODES.md) | Các chế độ hoạt động: Plan / Agent / YOLO |
+| [MCP.md](docs/MCP.md) | Tích hợp giao thức Model Context Protocol |
+| [RUNTIME_API.md](docs/RUNTIME_API.md) | Hướng dẫn sử dụng máy chủ API HTTP/SSE |
+| [INSTALL.md](docs/INSTALL.md) | Hướng dẫn cài đặt riêng theo từng nền tảng |
+| [DOCKER.md](docs/DOCKER.md) | Sử dụng Docker image trên GHCR, volume lưu trữ |
+| [CNB_MIRROR.md](docs/CNB_MIRROR.md) | CNB mirror và các lưu ý cài đặt tại Trung Quốc |
+| [TENCENT_CLOUD_REMOTE_FIRST.md](docs/TENCENT_CLOUD_REMOTE_FIRST.md) | Hướng dẫn kết nối Tencent/CNB/Lighthouse/Feishu từ xa |
+| [TENCENT_LIGHTHOUSE_HK.md](docs/TENCENT_LIGHTHOUSE_HK.md) | Thiết lập máy chủ Lighthouse Hồng Kông |
+| [MEMORY.md](docs/MEMORY.md) | Hướng dẫn tính năng tự ghi nhớ thông tin người dùng |
+| [SUBAGENTS.md](docs/SUBAGENTS.md) | Phân loại vai trò và vòng đời của các sub-agent con |
+| [KEYBINDINGS.md](docs/KEYBINDINGS.md) | Danh sách phím tắt đầy đủ |
+| [RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) | Quy trình đóng gói và phát hành phiên bản mới |
+| [LOCALIZATION.md](docs/LOCALIZATION.md) | Ma trận đa ngôn ngữ giao diện & cách chuyển đổi |
+| [OPERATIONS_RUNBOOK.md](docs/OPERATIONS_RUNBOOK.md) | Vận hành và phục hồi hệ thống |
+
+Lịch sử cập nhật chi tiết: [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## Lời cảm ơn
+
+- **[DeepSeek](https://github.com/deepseek-ai)** — Xin chân thành cảm ơn sự hỗ trợ và các mô hình AI mạnh mẽ giúp tiếp sức cho mọi tương tác trong dự án. 感谢 DeepSeek 提供模型与支持，让每一次交互成为可能。
+- **[DataWhale](https://github.com/datawhalechina)** 🐋 — Xin cảm ơn sự hỗ trợ nhiệt tình và đã chào đón chúng tôi gia nhập gia đình lớn "Whale Brother". 感谢 DataWhale 的支持，并欢迎 chúng tôi gia nhập “鲸兄弟”大家庭。
+- **[OpenWarp](https://github.com/zerx-lab/warp)** — Cảm ơn vì đã ưu tiên hỗ trợ codewhale và hợp tác để mang lại trải nghiệm agent terminal tốt hơn.
+- **[Open Design](https://github.com/nexu-io/open-design)** — Cảm ơn vì sự hỗ trợ và hợp tác xung quanh quy trình làm việc chú trọng thiết kế của agent.
+
+Dự án này được phát triển và vận hành trơn tru với sự đóng góp của cộng đồng các nhà phát triển ngày càng lớn mạnh:
+
+- **[merchloubna70-dot](https://github.com/merchloubna70-dot)** — Đóng góp 28 PR bao gồm tính năng mới, sửa lỗi và dựng sẵn extension cho VS Code (#645–#681)
+- **[WyxBUPT-22](https://github.com/WyxBUPT-22)** — Xây dựng trình kết xuất Markdown hỗ trợ bảng biểu, chữ đậm/nghiêng và đường kẻ ngang (#579)
+- **[loongmiaow-pixel](https://github.com/loongmiaow-pixel)** — Tài liệu cài đặt cho Windows và Trung Quốc (#578)
+- **[20bytes](https://github.com/20bytes)** — Cải tiến tài liệu tính năng tự ghi nhớ và giao diện trợ giúp (#569)
+- **[staryxchen](https://github.com/staryxchen)** — Kiểm tra độ tương thích của thư viện glibc trước khi chạy (#556)
+- **[Vishnu1837](https://github.com/Vishnu1837)** — Tối ưu hóa tính tương thích glibc và tự phục hồi trạng thái terminal khi nhận tín hiệu SIGINT/SIGTERM (#565, #1586)
+- **[shentoumengxin](https://github.com/shentoumengxin)** — Kiểm tra hợp lệ ranh giới thư mục làm việc `cwd` của Shell (#524)
+- **[toi500](https://github.com/toi500)** — Báo cáo và sửa lỗi dán văn bản trên hệ điều hành Windows
+- **[xsstomy](https://github.com/xsstomy)** — Báo cáo lỗi vẽ lại màn hình khi khởi động terminal
+- **Melody0709** — Báo cáo lỗi kích hoạt phím Enter với tiền tố lệnh gạch chéo
+- **[lloydzhou](https://github.com/lloydzhou)** và **[jeoor](https://github.com/jeoor)** — Báo cáo lỗi chi phí nén dữ liệu; lloydzhou cũng đóng góp ngữ cảnh môi trường xác định (#813, #922) và ổn định bộ nhớ đệm KV prefix-cache (#1080)
+- **[Agent-Skill-007](https://github.com/Agent-Skill-007)** — Tinh chỉnh diễn đạt rõ ràng cho file giới thiệu README (#685)
+- **[woyxiang](https://github.com/woyxiang)** — Tài liệu hướng dẫn cài đặt qua Scoop trên Windows (#696)
+- **[wangfeng](mailto:wangfengcsu@qq.com)** — Cập nhật thông tin giá cả và chương trình khuyến mãi (#692)
+- **[zichen0116](https://github.com/zichen0116)** — Xây dựng tài liệu quy tắc ứng xử cộng đồng CODE_OF_CONDUCT.md (#686)
+- **[dfwqdyl-ui](https://github.com/dfwqdyl-ui)** — Báo cáo tính tương thích chữ hoa/thường của ID mô hình (#729)
+- **[Oliver-ZPLiu](https://github.com/Oliver-ZPLiu)** — Báo cáo lỗi trạng thái `working...` bị kẹt, cơ chế dự phòng khay nhớ tạm (clipboard) trên Windows, sửa lỗi phiên kết nối HTTP dạng MCP Streamable, và tự động hóa brew tap (#738, #850, #1643, #1631)
+- **[reidliu41](https://github.com/reidliu41)** — Ý tưởng gợi ý tiếp tục phiên, lưu trữ độ tin cậy workspace, hỗ trợ nhà cung cấp Ollama, hoàn thiện stream khối suy nghĩ, tăng cường cache cho CI, xử lý wrap dòng stream, và hoàn thành tính năng autocomplete cho DeepSeek (#863, #870, #921, #1078, #1603, #1628, #1601)
+- **[xieshutao](https://github.com/xieshutao)** — Cơ chế dự phòng skill dạng Markdown thuần (#869)
+- **[GK012](https://github.com/GK012)** — Cơ chế dự phòng lệnh `--version` của wrapper npm (#885)
+- **[y0sif](https://github.com/y0sif)** — Xử lý đánh thức vòng lặp agent cha sau khi các sub-agent con hoàn thành tác vụ (#901)
+- **[mac119](https://github.com/mac119)** và **[leo119](https://github.com/leo119)** — Viết tài liệu hướng dẫn cho lệnh `codewhale update` (#838, #917)
+- **[dumbjack](https://github.com/dumbjack)** / **浩淼的mac** — Tăng cường bảo mật chống mã độc qua lệnh shell byte rỗng (#706, #918)
+- **macworkers** — Cải tiến xác nhận rẽ nhánh (fork) kèm mã phiên làm việc mới (#600, #919)
+- **zero** và **[zerx-lab](https://github.com/zerx-lab)** — Cấu hình điều kiện nhận thông báo và làm phong phú nội dung thông báo qua OSC 9 (#820, #920)
+- **[chnjames](https://github.com/chnjames)** — Gợi ý hoàn thành @mentions từ cache, cải tiến phục hồi file cấu hình lỗi, và hiển thị chuẩn UTF-8 cho Shell trên Windows (#849, #927, #982, #1018)
+- **[angziii](https://github.com/angziii)** — Bảo mật cấu hình, dọn dẹp tài nguyên bất đồng bộ, tăng cường bảo mật Docker và vá lỗi an toàn thực thi lệnh (#822, #824, #827, #831, #833, #835, #837)
+- **[elowen53](https://github.com/elowen53)** — Giải mã UTF-8 và bổ sung các ca kiểm thử xác định (#825, #840)
+- **[wdw8276](https://github.com/wdw8276)** — Bổ sung lệnh `/rename` để đổi tên tiêu đề phiên làm việc tùy chỉnh (#836)
+- **[banqii](https://github.com/banqii)** — Hỗ trợ đường dẫn tìm kiếm skill dạng `.cursor/skills` (#817)
+- **[junskyeed](https://github.com/junskyeed)** — Tính toán động giá trị `max_tokens` cho các yêu cầu API (#826)
+- **Hafeez Pizofreude** — Triển khai cơ chế chống tấn công SSRF trong công cụ `fetch_url` và biểu đồ lịch sử Star History.
+- **Unic (YuniqueUnic)** — Xây dựng giao diện cấu hình tự động dựa trên schema (cả TUI và web).
+- **Jason** — Tăng cường bảo mật an toàn mạng chống tấn công giả mạo yêu cầu từ phía máy chủ (SSRF).
+- **[axobase001](https://github.com/axobase001)** — Dọn dẹp snapshot mồ côi, bổ sung bộ bảo vệ khi cài npm, sửa lỗi đo lường phiên làm việc, xóa cache phạm vi mô hình, hỗ trợ các liên kết tượng trưng (symlinks) cho skill, hướng dẫn cơ chế thoát lỗi cài đặt npm mirror, và duy trì cấu hình proxy cho các tác vụ con (#975, #1032, #1047, #1049, #1052, #1019, #1051, #1056, #1608)
+- **[MengZ-super](https://github.com/MengZ-super)** — Xây dựng nền tảng cho lệnh `/theme` và giải nén dữ liệu nén dạng gzip/brotli cho kết nối SSE (#1057, #1061)
+- **[DI-HUO-MING-YI](https://github.com/DI-HUO-MING-YI)** — Vá lỗi bảo mật sandbox chỉ đọc trong chế độ Plan (#1077)
+- **[bevis-wong](https://github.com/bevis-wong)** — Cung cấp ca tái hiện chính xác lỗi tự động gửi tin khi dán văn bản kèm ký tự xuống dòng (#1073)
+- **[Duducoco](https://github.com/Duducoco)** và **[AlphaGogoo](https://github.com/AlphaGogoo)** — Xây dựng thanh menu gạch chéo cho skill và sửa lỗi bao phủ lệnh `/skills` (#1068, #1083)
+- **[ArronAI007](https://github.com/ArronAI007)** — Sửa lỗi hiển thị tài nguyên artifact khi thay đổi kích thước cửa sổ trên macOS Terminal.app và ConHost (#993)
+- **[THINKER-ONLY](https://github.com/THINKER-ONLY)** — Duy trì mã mô hình tùy chỉnh cho OpenRouter và endpoint riêng (#1066)
+- **[Jefsky](https://github.com/Jefsky)** — Báo cáo sửa lỗi địa chỉ endpoint chính thức của DeepSeek (#1079, #1084)
+- **[wlon](https://github.com/wlon)** — Chẩn đoán và ưu tiên lựa chọn khóa xác thực cho nhà cung cấp NVIDIA NIM (#1081)
+- **[Horace Liu](https://github.com/liuhq)** — Đóng gói hỗ trợ Nix package và viết tài liệu hướng dẫn cài đặt (#1173)
+- **[jieshu666](https://github.com/jieshu666)** — Giảm thiểu hiện tượng nhấp nháy màn hình khi vẽ lại giao diện TUI (#1563)
+- **[gordonlu](https://github.com/gordonlu)** — Sửa lỗi nhận dạng phím Enter / mã nhập CSI-u trên Windows (#1612)
+- **[mdrkrg](https://github.com/mdrkrg)** — Vá lỗi sập ứng dụng trong lần chạy đầu tiên khi thiếu khóa API (#1598)
+- **[Aitensa](https://github.com/Aitensa)** — Xử lý tự động xuống dòng CJK cho các khối diff và kết quả đầu ra trang giấy (#1622)
+- **[qiyan233](https://github.com/qiyan233)** — Đảm bảo tương thích với các bí danh cũ của nhà cung cấp DeepSeek Trung Quốc (#1645)
+- **[zlh124](https://github.com/zlh124)** — Báo cáo khởi động không đầu WSL2 và sửa lỗi khay nhớ tạm (#1772, #1773)
+- **[aboimpinto](https://github.com/aboimpinto)** — Sửa lỗi ghi nhật ký màn hình phụ trên Windows, hoàn thiện phím Home/End tại bộ soạn thảo và theo dõi log runtime (#1774, #1776, #1748, #1749, #1782, #1783)
+- **[LeoLin990405](https://github.com/LeoLin990405)** — Bổ sung cơ chế truyền thẳng mô hình qua provider, phát lại luồng suy nghĩ, tối ưu lượt chạy chỉ suy nghĩ, và sửa lỗi trích dẫn trên Windows (#1740, #1743, #1742, #1744)
+- **[nightt5879](https://github.com/nightt5879)** — Khắc phục lỗi khôi phục giao diện nhắc nhở khi bấm phím Ctrl+C (#1764)
+- **[donglovejava](https://github.com/donglovejava)** — Hợp nhất kéo thả dán tệp `@file`, vá lỗi sập chữ CJK, thu thập phản hồi người dùng, định tuyến RLM, và thử lại khi `edit_file` bị kẹt (#2154–#2168)
+- **[encyc](https://github.com/encyc)** — Hiển thị chi tiết số lượng token tiêu thụ ở chân trang và lệnh `/status` (#2152)
+- **[saieswar237](https://github.com/saieswar237)** — Bổ sung tài liệu hướng dẫn về quy trình review code (#2178)
+- **[sximelon](https://github.com/sximelon)** — Chặn sự kiện tự gửi tin khi dán văn bản và tách phân hệ quản lý phím bấm (#2174, #2042)
+- **[nanookclaw](https://github.com/nanookclaw)** — Bổ sung hiển thị nhà cung cấp tìm kiếm trong kết quả của lệnh doctor (#2135)
+- **[Sskift](https://github.com/Sskift)** — Ngăn chặn việc ghi đè biến môi trường mặc định trên CLI (#2119)
+- **[xin1104](https://github.com/xin1104)** — Tạo brew formula cài binary codewhale độc lập (#2105)
+- **[mrluanma](https://github.com/mrluanma)** — Bổ sung nhà cung cấp dịch vụ tìm kiếm Metaso (#2059)
+- **[Lellansin](https://github.com/Lellansin)** — Bỏ qua việc gộp cấu hình tại thư mục home người dùng (#2055)
+- **[zhuangbiaowei](https://github.com/zhuangbiaowei)** — Cập nhật các kênh phát hành chính thức của sản phẩm (#2145)
+
+---
+
+## Đóng góp cho dự án
+
+Xem tài liệu hướng dẫn đóng góp tại [CONTRIBUTING.md](CONTRIBUTING.md). Chúng tôi luôn hoan nghênh các yêu cầu kéo Pull Requests — vui lòng xem danh sách các [vấn đề mở (open issues)](https://github.com/Hmbown/CodeWhale/issues) để bắt đầu đóng góp những phần việc đầu tiên.
+
+Ủng hộ nhà phát triển: [Buy me a coffee](https://www.buymeacoffee.com/hmbown).
+
+> [!Note]
+> *Dự án này độc lập và không trực thuộc công ty DeepSeek Inc.*
+
+## Bản quyền
+
+[MIT](LICENSE)
+
+## Biểu đồ Star History
+
+[![Biểu đồ lịch sử sao](https://api.star-history.com/chart?repos=Hmbown/CodeWhale&type=date&legend=top-left)](https://www.star-history.com/?repos=Hmbown%2FCodeWhale&type=date&logscale=&legend=top-left)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 97fd11eb..7fa6bca5 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,46 +1,44 @@
 # CodeWhale
 
-> **DeepSeek 优先、面向开源与开放权重编码模型的终端原生编程智能体：100 万 token 上下文、思考模式流式推理、前缀缓存感知。自包含 Rust 二进制发布——开箱即带 MCP 客户端、沙箱和持久化任务队列。**
-
-[![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale)
-[![crates.io](https://img.shields.io/crates/v/codewhale-cli?label=crates.io)](https://crates.io/crates/codewhale-cli)
-[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Hmbown)
-[DeepWiki project index](https://deepwiki.com/Hmbown/CodeWhale)
+> **面向 [DeepSeek V4](https://platform.deepseek.com) 的终端原生编程智能体：100 万 token 上下文、思考模式流式推理、前缀缓存感知。以 `codewhale` 调度器和 `codewhale-tui` 运行时这一组自包含 Rust 二进制发布——开箱即带 MCP 客户端、沙箱和持久化任务队列。**
 
 [English README](README.md)
 [日本語 README](README.ja-JP.md)
+[Tiếng Việt README](README.vi.md)
 
-[安装](#安装) · [快速开始](#快速开始) · [使用方式](#使用方式) · [文档](#文档) · [贡献](#贡献) · [支持](#支持)
 
 ## 安装
 
-`codewhale` 是自包含 Rust 二进制——**运行时不依赖 Node.js 或 Python**。
-下面几种方式装出来的是同一套二进制，按你已有的工具链选一个即可：
+`codewhale` 以一组自包含 Rust 发布二进制安装：`codewhale` 调度器命令，
+以及它在交互会话中启动的同级 `codewhale-tui` 运行时。npm、Homebrew 和
+Docker 会自动安装这两个二进制；Cargo 或手动下载时必须把两者放在同一目录
+（通常是 `PATH` 上的某个目录）。运行时不依赖 Node.js 或 Python。
 
 ```bash
 # 1. npm —— 已装 Node 的最方便方式。npm 包只是一个下载器，
-#    会从 GitHub Releases 拉取对应平台的预编译二进制，
+#    会从 GitHub Releases 拉取对应平台的预编译二进制对，
 #    并不会让 codewhale 本身依赖 Node 运行时。
 npm install -g codewhale
 
-# 2. Cargo —— 无需 Node。
+# 2. Cargo —— 无需 Node，两个 crate 都要安装。
 cargo install codewhale-cli --locked   # `codewhale` 入口
 cargo install codewhale-tui     --locked   # `codewhale-tui` TUI 二进制
 
 # 3. Homebrew —— macOS 包管理器。
+#    tap/formula 名称仍是旧名；实际安装 codewhale 和 codewhale-tui。
 brew tap Hmbown/deepseek-tui
 brew install deepseek-tui
 
-# 4. 直接下载 —— 无需任何工具链。
+# 4. 直接下载 —— GitHub Releases 的平台压缩包。
 #    https://github.com/Hmbown/CodeWhale/releases
-#    覆盖 Linux x64/ARM64、macOS x64/ARM64、Windows x64
+#    压缩包包含 codewhale 和 codewhale-tui 以及安装脚本；
+#    也提供单独二进制给脚本使用，手动安装时请把这一对放在一起。
 
 # 5. Docker —— 预构建发布镜像。
 docker volume create codewhale-home
 docker run --rm -it \
   -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-  -v codewhale-home:/home/codewhale/.deepseek \
+  -v codewhale-home:/home/codewhale/.codewhale \
   -v "$PWD:/workspace" \
   -w /workspace \
   ghcr.io/hmbown/codewhale:latest
@@ -63,6 +61,13 @@ brew update && brew upgrade deepseek-tui
 cargo install codewhale-cli --locked --force
 cargo install codewhale-tui     --locked --force
 ```
+> codewhale update 现在可添加 --proxy ,通过代理下载更新
+> eg: codewhale update --proxy https://localhost:7897
+
+[![CI](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml/badge.svg)](https://github.com/Hmbown/CodeWhale/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/codewhale)](https://www.npmjs.com/package/codewhale)
+[![crates.io](https://img.shields.io/crates/v/codewhale-cli?label=crates.io)](https://crates.io/crates/codewhale-cli)
+[DeepWiki project index](https://deepwiki.com/Hmbown/CodeWhale)
 
 ![codewhale 截图](assets/screenshot.png)
 
@@ -70,37 +75,43 @@ cargo install codewhale-tui     --locked --force
 
 ## 这是什么？
 
-codewhale 是一个完全运行在终端里的编程智能体。它让 DeepSeek 前沿模型直接访问你的工作区：读写文件、运行 shell 命令、搜索浏览网页、管理 git、调度子智能体——全部通过快速、键盘驱动的 TUI 完成。
+模型回答问题。智能体完成任务。区别在于运行框架——一套在模型偏离时保持方向的规则、证据和反馈系统。
 
-它面向 **DeepSeek V4**（`deepseek-v4-pro` / `deepseek-v4-flash`）构建，原生支持 100 万 token 上下文窗口和思考模式流式输出。
+CodeWhale 就是这套框架，围绕 DeepSeek V4 构建，基于三个理念：
 
-### 主要功能
+| 原则 | 如何运作 |
+|---|---|
+| **从信任开始** | 每一轮以"A"开始——可能性先于确定性，匠心先于便利 |
+| **清晰的管辖权** | 成文宪法，九层权威。用户意图优先于陈旧指令。验证优先于自信。 |
+| **递归改进** | V4 参与了框架的编写。框架改进 → V4 更高效 → 进一步改进框架。每轮从更强的位置开始。 |
 
-- **模型自动路由** —— `--model auto` / `/model auto` 每轮自动选择模型和推理强度
-- **Fin 快速通道** —— 使用关闭思考的低成本 `deepseek-v4-flash` 承担路由、RLM 子调用、摘要和协调工作
-- **原生 RLM**（`rlm_open`/`rlm_eval`）—— 持久化 REPL 会话用于批量分析；使用带界面的辅助函数（`peek`、`search`、`chunk`、`sub_query_batch`）
-- **思考模式流式输出** —— 实时观察模型在解决问题时的思维链展开
-- **完整工具集** —— 文件操作、shell 执行、git、网页搜索/浏览、apply-patch、子智能体、MCP 服务器
-- **100 万 token 上下文** —— 上下文跟踪、手动或配置驱动的压缩，以及前缀缓存遥测
-- **前缀缓存稳定性跟踪** —— 可选 `/statusline` footer chip 显示最近轮次缓存前缀的稳定程度
-- **三种交互模式** —— Plan（只读探索）、Agent（带审批的默认交互）、YOLO（可信工作区自动批准）
-- **推理强度档位** —— 用 `Shift+Tab` 在 `off → high → max` 之间切换
-- **会话保存和恢复** —— 长任务的断点续作
-- **工作区回滚** —— 通过 side-git 记录每轮前后快照，支持 `/restore` 和 `revert_turn`，不影响项目自己的 `.git`
-- **持久化任务队列** —— 后台任务在重启后仍然存在，支持计划任务和长时间运行的操作
-- **HTTP/SSE 运行时 API** —— `codewhale serve --http` 用于无界面智能体流程
-- **MCP 协议** —— 连接 Model Context Protocol 服务器扩展工具，见 [docs/MCP.md](docs/MCP.md)
-- **LSP 诊断** —— 每次编辑后通过 rust-analyzer、pyright、typescript-language-server、gopls、clangd 提供内联错误/警告
-- **用户记忆** —— 可选的持久化笔记文件注入系统提示，实现跨会话偏好保持
-- **多语言 UI** —— 支持 `en`、`ja`、`zh-Hans`、`pt-BR`，支持自动检测
-- **实时成本跟踪** —— 按轮次和会话统计 token 用量与成本估算，含缓存命中/未命中明细；简体中文 locale 下显示 CNY
-- **技能系统** —— 可通过 GitHub 安装的组合式指令包；首次启动自带 `skill-creator`、`mcp-builder`、`documents`、`presentations`、`spreadsheets`、`pdf`、`feishu` 等 starter skills
-- **终端原生通知** —— OSC 9、OSC 99、OSC 777，以及桌面通知兜底
-- **内置主题选择器** —— Catppuccin、Tokyo Night、Dracula、Gruvbox 和原有亮/暗色主题，可用 `/theme` 实时切换
+开源、终端原生，并以 `codewhale` / `codewhale-tui` 这一组 Rust 二进制发布。
+
+## 框架如何工作
+
+智能体模型面临大规模的冲突信息：用户意图、项目规则、系统默认值、工具输出和陈旧记忆在单轮对话中争夺权威。LLM 作为裁判需要管辖权——当它们冲突时，哪个来源胜出？
+
+CodeWhale 用一部**宪法**（`prompts/base.md`）来回答这个问题。它是一个形式化的法律层级——第七条将九个来源从宪法本身的条款排到前序会话的交接记录。用户当前消息优先于陈旧的项目指令。实时工具输出优先于假设。验证优先于自信。模型每轮继承清晰的权威链，永远不需要猜测该服从哪条指令。
+
+七条条款位于层级之上，定义模型的身份、职责和能动性：验证强制（第五条——每个行动留下证据，绝不凭信念宣告成功）、协作遗产（第六条——让工作区对下一位智能体保持可读）、以及真相优先条款（第二条——任何下级规则不得覆盖它）。
+
+DeepSeek V4 的前缀缓存使其可行。宪法篇幅长且详细，但一旦缓存，每轮成本约为冷读取的百分之一。模型递归引用它——通过 RLM 会话窥视、扫描和查询——按需重访信息，而非依赖单次记忆读取。它的表现更像是开卷考试而非闭卷考试。
+
+因为权威结构是显式的，失败不会被隐藏。非零退出码、两次轮次间来自 rust-analyzer 的类型错误、沙箱拒绝——这些被作为修正向量反馈。模型用自己的漂移进行自我校正。
+
+三种模式控制行动空间。Plan 只读。Agent 对破坏性操作设审批门控。YOLO 在可信工作区自动批准。macOS Seatbelt 是主动执行的沙箱；Linux Landlock 可检测但未执行；Windows 沙箱尚未开放。
+
+Fin——关闭思考的廉价 Flash 调用——每轮处理模型自动路由。`--model auto` 是默认值。
+
+每轮记录 side-git 快照，在仓库 `.git` 之外。`/restore` 和 `revert_turn` 即刻回滚工作区。
+
+子智能体并发运行（最多 20 个）。`agent_open` 立即返回；结果以内联完成哨兵形式到达，携带摘要。完整对话记录通过 `agent_eval` 的有界句柄保存。详见 [docs/SUBAGENTS.md](docs/SUBAGENTS.md)。
+
+其余功能面：每次编辑后的 LSP 诊断（rust-analyzer、pyright、typescript-language-server、gopls、clangd、jdtls、vue-language-server）、RLM 会话批量分析、MCP 协议、HTTP/SSE 运行时 API、持久化任务队列、Zed 的 ACP 适配器、SWE-bench 导出、以及带缓存命中/未命中明细的实时成本追踪。
 
 ---
 
-## 架构说明
+## 运行框架
 
 `codewhale`（调度器 CLI）→ `codewhale-tui`（伴随二进制）→ ratatui 界面 ↔ 异步引擎 ↔ OpenAI 兼容流式客户端。工具调用通过类型化注册表（shell、文件操作、git、web、子智能体、MCP、RLM）路由，结果流式返回对话记录。引擎管理会话状态、轮次追踪、持久化任务队列和 LSP 子系统——它在下一步推理前将编辑后诊断反馈到模型上下文中。
 
@@ -112,8 +123,8 @@ codewhale 可以同时调度多个子智能体并行运行——类似于并发
 
 - **非阻塞启动。** `agent_open` 立即返回。子智能体获得独立的上下文和工具注册表，独立运行。父进程继续工作。
 - **后台执行。** 子智能体并发运行（默认上限 10，可配置至 20）。引擎管理线程池——无需轮询循环。
-- **完成通知。** 子智能体完成后，运行时发送结构化的 `<codewhale:subagent.done>` 事件，包含摘要、证据列表和执行指标。父模型读取 `summary` 字段并整合结果。
-- **按需读取结果。** 大型对话记录暂存为 `var_handle` 引用。模型通过 `handle_read` 按切片、范围或 JSONPath 投影读取——保持父上下文精简。
+- **完成通知。** 子智能体完成后，运行时向父对话注入 `<codewhale:subagent.done>` 哨兵。人类可读的摘要（包含子智能体的发现、变更文件和风险）位于哨兵的紧前一行。父模型读取该摘要并整合结果，无需额外工具调用。
+- **按需读取结果。** 完整子对话记录通过 `agent_eval` 获取的 `transcript_handle` 暂存。摘要不够时，父进程通过 `handle_read` 按切片、行范围或 JSONPath 投影读取——保持父上下文精简而不丢失细节。
 
 详见 [docs/SUBAGENTS.md](docs/SUBAGENTS.md)。
 
@@ -127,14 +138,14 @@ codewhale --version
 codewhale --model auto
 ```
 
-预构建二进制覆盖 **Linux x64**、**Linux ARM64**（v0.8.8 起）、**macOS x64**、**macOS ARM64** 和 **Windows x64**。其他目标平台（musl、riscv64、FreeBSD 等）请见下方的[从源码安装](#从源码安装)或 [docs/INSTALL.md](docs/INSTALL.md)。
+预构建二进制对和平台压缩包覆盖 **Linux x64**、**Linux ARM64**（v0.8.8 起）、**macOS x64**、**macOS ARM64** 和 **Windows x64**。其他目标平台（musl、riscv64、FreeBSD 等）请见下方的[从源码安装](#从源码安装)或 [docs/INSTALL.md](docs/INSTALL.md)。
 
-首次启动时会提示输入 [DeepSeek API key](https://platform.deepseek.com/api_keys)。密钥保存到 `~/.deepseek/config.toml`，在任意目录、IDE 终端和脚本中都能使用，不会触发系统密钥环弹窗。
+首次启动时会提示输入 [DeepSeek API key](https://platform.deepseek.com/api_keys)。密钥保存到 `~/.codewhale/config.toml`（同时兼容旧版 `~/.deepseek/config.toml`），在任意目录、IDE 终端和脚本中都能使用，不会触发系统密钥环弹窗。
 
 也可以提前配置：
 
 ```bash
-codewhale auth set --provider deepseek   # 保存到 ~/.deepseek/config.toml
+codewhale auth set --provider deepseek   # 保存到 ~/.codewhale/config.toml
 
 codewhale auth status                    # 显示当前活跃的凭证来源
 export DEEPSEEK_API_KEY="YOUR_KEY"      # 环境变量方式；需要在非交互式 shell 中使用请放入 ~/.zshenv
@@ -155,18 +166,18 @@ CNB 镜像/源码，腾讯云 Lighthouse 香港实例，飞书/Lark 长连接桥
 先看 [docs/TENCENT_CLOUD_REMOTE_FIRST.md](docs/TENCENT_CLOUD_REMOTE_FIRST.md)，
 再按 [docs/TENCENT_LIGHTHOUSE_HK.md](docs/TENCENT_LIGHTHOUSE_HK.md) 配置服务器。
 
-### 模型自动路由与 Fin
+### Auto 模式
 
 使用 `codewhale --model auto` 或 `/model auto` 让 codewhale 自行决定每轮需要多少模型和推理能力。
 
-模型自动路由同时控制两个设置：
+Auto 模式同时控制两个设置：
 
 - 模型：`deepseek-v4-flash` 或 `deepseek-v4-pro`
 - 推理强度：`off`、`high` 或 `max`
 
-在真实请求发出之前，应用会先用关闭推理的 `deepseek-v4-flash` 进行一次小型路由调用。这条快速路径叫 **Fin**：用于模型选择、摘要、RLM 子任务、上下文维护以及其他不该消耗完整推理轮次的协调工作。Fin 审视最新请求和最近的上下文，然后为真实请求选定具体的模型和推理强度。简短/简单的轮次保持在 Flash + 关闭推理；编码、调试、发布、架构、安全审查或模糊的多步骤任务可升级到 Pro 和/或更高推理强度。
+在真实请求发出之前，应用会先用关闭推理的 `deepseek-v4-flash` 进行一次小型路由调用。路由器审视最新请求和最近的上下文，然后为真实请求选定具体的模型和推理强度。简短/简单的轮次保持在 Flash + 关闭推理；编码、调试、发布、架构、安全审查或模糊的多步骤任务可升级到 Pro 和/或更高推理强度。
 
-`--model auto` 和 `/model auto` 是 codewhale 本地行为。上游 API 永远不会收到 `model: "auto"`，它只会收到为当前轮次选定的具体模型和推理强度设置。TUI 会显示选定的路由，成本跟踪按实际运行的模型计费。如果 Fin 路由失败或返回无效答案，应用会回退到本地启发式规则。子智能体会继承模型自动路由，除非你为它们指定了显式模型。
+`auto` 是 codewhale 本地行为。上游 API 永远不会收到 `model: "auto"`，它只会收到为当前轮次选定的具体模型和推理强度设置。TUI 会显示选定的路由，成本跟踪按实际运行的模型计费。如果路由调用失败或返回无效答案，应用会回退到本地启发式规则。子智能体会继承 auto 模式，除非你为它们指定了显式模型。
 
 需要可重复基准测试、严格控制成本上限或特定提供商/模型映射时，请使用固定模型或固定推理强度。
 
@@ -205,7 +216,7 @@ release。先运行 `scoop update`，安装后用 `codewhale --version` 核对
 
 ```bash
 scoop update
-scoop install deepseek-tui
+scoop install codewhale
 codewhale --version
 ```
 
@@ -252,6 +263,10 @@ codewhale --provider wanjie-ark --model deepseek-reasoner
 codewhale auth set --provider openrouter --api-key "YOUR_OPENROUTER_API_KEY"
 codewhale --provider openrouter --model deepseek/deepseek-v4-pro
 
+# Xiaomi MiMo
+codewhale auth set --provider xiaomi-mimo --api-key "YOUR_XIAOMI_MIMO_API_KEY"
+codewhale --provider xiaomi-mimo --model mimo-v2.5-pro
+
 # Novita
 codewhale auth set --provider novita --api-key "YOUR_NOVITA_API_KEY"
 codewhale --provider novita --model deepseek/deepseek-v4-pro
@@ -293,10 +308,10 @@ codewhale --provider ollama --model codewhale-coder:1.3b
 ```bash
 codewhale                                       # 交互式 TUI
 codewhale "explain this function"              # 一次性提示
-codewhale exec --auto --output-format stream-json "fix this bug" # 自动批准工具的 agentic exec
+codewhale exec --auto --output-format stream-json "fix this bug" # 面向后端集成的 NDJSON 流
 codewhale exec --resume <SESSION_ID> "follow up" # 继续非交互会话
 codewhale --model deepseek-v4-flash "summarize" # 指定模型
-codewhale --model auto "fix this bug"          # 自动路由模型 + 推理强度
+codewhale --model auto "fix this bug"          # 自动选择模型 + 推理强度
 codewhale --yolo                                # 自动批准工具
 codewhale auth set --provider deepseek         # 保存 API key
 codewhale doctor                                # 检查配置和连接
@@ -309,6 +324,7 @@ codewhale resume --last                         # 恢复最近会话
 codewhale resume <SESSION_ID>                   # 按 UUID 恢复指定会话
 codewhale fork <SESSION_ID>                     # 将已保存会话分叉为兄弟路径
 codewhale serve --http                          # HTTP/SSE API 服务
+codewhale serve --mobile                        # 局域网移动端控制页，默认启用 token 保护
 codewhale serve --acp                           # Zed/自定义智能体的 ACP stdio 适配器
 codewhale run pr <N>                            # 获取 PR 并预填审查提示
 codewhale mcp list                              # 列出已配置 MCP 服务器
@@ -324,7 +340,7 @@ docker volume create codewhale-home
 
 docker run --rm -it \
   -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
-  -v codewhale-home:/home/codewhale/.deepseek \
+  -v codewhale-home:/home/codewhale/.codewhale \
   -v "$PWD:/workspace" \
   -w /workspace \
   ghcr.io/hmbown/codewhale:latest
@@ -378,15 +394,11 @@ DeepSeek 可作为自定义 Agent Client Protocol 服务器运行，供 Zed 等
 | **Agent** 🤖 | 默认交互模式；多步工具调用带审批门禁 |
 | **YOLO** ⚡ | 在可信工作区自动批准工具；仍会维护计划和清单以保持可见性 |
 
-模式与模型自动路由是两个概念。`Tab` 切换 Plan / Agent / YOLO，
-`/model auto` 选择模型和思考强度。`/goal` 当前用于追踪会话目标和
-token 预算；未来如果扩展成 Goal 工作区，也应与 `--model auto` 保持独立。
-
 ---
 
 ## 配置
 
-用户配置：`~/.deepseek/config.toml`。项目覆盖：`<workspace>/.deepseek/config.toml`（以下密钥被拒绝：`api_key`、`base_url`、`provider`、`mcp_config_path`）。完整选项见 [config.example.toml](config.example.toml)。
+用户配置：`~/.codewhale/config.toml`（兼容旧版 `~/.deepseek/config.toml`）。项目覆盖：`<workspace>/.codewhale/config.toml`（兼容 `<workspace>/.deepseek/config.toml`）（以下密钥被拒绝：`api_key`、`base_url`、`provider`、`mcp_config_path`）。完整选项见 [config.example.toml](config.example.toml)。
 
 常用环境变量：
 
@@ -397,15 +409,16 @@ token 预算；未来如果扩展成 Goal 工作区，也应与 `--model auto` 
 | `DEEPSEEK_HTTP_HEADERS` | 可选模型请求头，例如 `X-Model-Provider-Id=your-model-provider` |
 | `DEEPSEEK_MODEL` | 默认模型 |
 | `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` | 流式响应空闲超时秒数，默认 `300`，限制在 `1..=3600` |
-| `DEEPSEEK_PROVIDER` | `codewhale`（默认）、`nvidia-nim`、`openai`、`atlascloud`、`wanjie-ark`、`openrouter`、`novita`、`fireworks`、`sglang`、`vllm`、`ollama` |
+| `DEEPSEEK_PROVIDER` | `codewhale`（默认）、`nvidia-nim`、`openai`、`atlascloud`、`wanjie-ark`、`openrouter`、`xiaomi-mimo`、`novita`、`fireworks`、`sglang`、`vllm`、`ollama` |
 | `DEEPSEEK_PROFILE` | 配置 profile 名称 |
 | `DEEPSEEK_MEMORY` | 设为 `on` 启用用户记忆 |
 | `DEEPSEEK_ALLOW_INSECURE_HTTP=1` | 在可信网络上允许非本机 `http://` API base URL |
-| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `OPENROUTER_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | 提供商认证 |
+| `NVIDIA_API_KEY` / `OPENAI_API_KEY` / `ATLASCLOUD_API_KEY` / `WANJIE_ARK_API_KEY` / `OPENROUTER_API_KEY` / `XIAOMI_MIMO_API_KEY` / `MIMO_API_KEY` / `NOVITA_API_KEY` / `FIREWORKS_API_KEY` / `SGLANG_API_KEY` / `VLLM_API_KEY` / `OLLAMA_API_KEY` | 提供商认证 |
 | `OPENAI_BASE_URL` / `OPENAI_MODEL` | 通用 OpenAI 兼容端点和模型 ID |
 | `ATLASCLOUD_BASE_URL` / `ATLASCLOUD_MODEL` | AtlasCloud 端点和模型覆盖 |
 | `WANJIE_ARK_BASE_URL` / `WANJIE_ARK_MODEL` | Wanjie Ark 端点和模型覆盖 |
 | `OPENROUTER_BASE_URL` | OpenRouter 端点覆盖 |
+| `XIAOMI_MIMO_BASE_URL` / `MIMO_BASE_URL` / `XIAOMI_MIMO_MODEL` / `MIMO_MODEL` | Xiaomi MiMo 端点和模型覆盖 |
 | `NOVITA_BASE_URL` | Novita 端点覆盖 |
 | `FIREWORKS_BASE_URL` | Fireworks 端点覆盖 |
 | `SGLANG_BASE_URL` | 自托管 SGLang 端点 |
@@ -428,10 +441,10 @@ token 预算；未来如果扩展成 Goal 工作区，也应与 `--model auto` 
 
 可选语言：`auto` | `en` | `ja` | `zh-Hans` | `pt-BR`。
 
-也可以在 `~/.deepseek/config.toml` 里直接设置 `locale = "zh-Hans"`，或通过 `LC_ALL` / `LANG` 环境变量自动选择：
+也可以在 `~/.codewhale/config.toml` 里直接设置 `locale = "zh-Hans"`，或通过 `LC_ALL` / `LANG` 环境变量自动选择：
 
 ```toml
-# ~/.deepseek/config.toml
+# ~/.codewhale/config.toml
 [tui]
 locale = "zh-Hans"
 ```
@@ -460,10 +473,10 @@ LANG=zh_CN.UTF-8 codewhale run
 
 ## 创建和安装技能
 
-codewhale 从工作区目录（`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills`）和全局 `~/.deepseek/skills` 发现技能。每个技能是一个包含 `SKILL.md` 的目录：
+codewhale 从工作区目录（`.agents/skills` → `skills` → `.opencode/skills` → `.claude/skills`）和全局 `~/.codewhale/skills`（兼容旧版 `~/.deepseek/skills`）发现技能。每个技能是一个包含 `SKILL.md` 的目录：
 
 ```text
-~/.deepseek/skills/my-skill/
+~/.codewhale/skills/my-skill/
 └── SKILL.md
 ```
 
@@ -491,7 +504,7 @@ description: 当 DeepSeek 需要遵循我的自定义工作流时使用这个技
 | [CONFIGURATION.md](docs/CONFIGURATION.md) | 完整配置参考 |
 | [MODES.md](docs/MODES.md) | Plan / Agent / YOLO 模式 |
 | [MCP.md](docs/MCP.md) | Model Context Protocol 集成 |
-| [RUNTIME_API.md](docs/RUNTIME_API.md) | HTTP/SSE API 服务 |
+| [RUNTIME_API.md](docs/RUNTIME_API.md) | HTTP/SSE API 服务和移动端控制页 |
 | [INSTALL.md](docs/INSTALL.md) | 各平台安装指南 |
 | [DOCKER.md](docs/DOCKER.md) | GHCR 镜像、volume 和 Docker 用法 |
 | [CNB_MIRROR.md](docs/CNB_MIRROR.md) | CNB 镜像和中国大陆友好安装说明 |
@@ -508,17 +521,6 @@ description: 当 DeepSeek 需要遵循我的自定义工作流时使用这个技
 
 ---
 
-## 支持
-
-CodeWhale 采用 MIT 许可证，使用和参与贡献都不需要赞助。如果它帮你节省了时间，
-最直接的长期支持方式是 [GitHub Sponsors](https://github.com/sponsors/Hmbown)。
-一次性支持也可以通过 [Buy Me a Coffee](https://www.buymeacoffee.com/hmbown) 完成。
-
-赞助会用于发布构建、CI/运行时测试、包发布，以及维护者处理 issue 和 review 的时间。
-功能请求、Bug 报告和 pull request 不需要赞助。
-
----
-
 ## 致谢
 
 - **[DeepSeek](https://github.com/deepseek-ai)** — 感谢 DeepSeek 提供模型与支持，让每一次交互成为可能。
@@ -538,15 +540,14 @@ CodeWhale 采用 MIT 许可证，使用和参与贡献都不需要赞助。如
 - **[toi500](https://github.com/toi500)** — Windows 粘贴修复报告
 - **[xsstomy](https://github.com/xsstomy)** — 终端启动重绘报告
 - **[melody0709](https://github.com/melody0709)** — 斜杠前缀回车激活报告
-- **[lloydzhou](https://github.com/lloydzhou)** 和 **[jeoor](https://github.com/jeoor)** — 压缩成本报告和 npm 安装器流暂停竞态修复 (#1860)；lloydzhou 还贡献了确定性的环境上下文注入 (#813, #922) 和 KV 前缀缓存稳定化 (#1080)
+- **[lloydzhou](https://github.com/lloydzhou)** 和 **[jeoor](https://github.com/jeoor)** — 压缩成本报告；lloydzhou 还贡献了确定性的环境上下文注入 (#813, #922) 和 KV 前缀缓存稳定化 (#1080)
 - **[Agent-Skill-007](https://github.com/Agent-Skill-007)** — README 清晰化改进 (#685)
 - **[woyxiang](https://github.com/woyxiang)** — Windows 安装文档 (#696)
 - **[wangfeng](mailto:wangfengcsu@qq.com)** — 价格/折扣信息更新 (#692)
 - **[zichen0116](https://github.com/zichen0116)** — CODE_OF_CONDUCT.md (#686)
 - **[dfwqdyl-ui](https://github.com/dfwqdyl-ui)** — 模型 ID 大小写兼容性报告 (#729)
 - **[Oliver-ZPLiu](https://github.com/Oliver-ZPLiu)** — `working...` 卡死状态 Bug 报告和 Windows 剪贴板兜底修复 (#738, #850)
-- **[reidliu41](https://github.com/reidliu41)** — 退出后的恢复提示、工作区信任持久化、Ollama provider 支持、思考块流式终结修复，以及帮助选择器选中行可见性优化 (#863, #870, #921, #1078, #1964)
-- **[cyq1017](https://github.com/cyq1017)** — Unicode `git_status` 路径、本地/配置技能发现，以及模式切换 toast 去重 (#1953, #1956, #1957)
+- **[reidliu41](https://github.com/reidliu41)** — 退出后的恢复提示、工作区信任持久化、Ollama provider 支持，以及思考块流式终结修复 (#863, #870, #921, #1078)
 - **[xieshutao](https://github.com/xieshutao)** — 纯 Markdown skill 兜底解析 (#869)
 - **[GK012](https://github.com/GK012)** — npm wrapper 的 `--version` 兜底 (#885)
 - **[y0sif](https://github.com/y0sif)** — 直接子智能体完成后唤醒父级 turn loop (#901)
@@ -572,82 +573,16 @@ CodeWhale 采用 MIT 许可证，使用和参与贡献都不需要赞助。如
 - **[THINKER-ONLY](https://github.com/THINKER-ONLY)** — OpenRouter 和自定义端点模型 ID 保留 (#1066)
 - **[Jefsky](https://github.com/Jefsky)** — `deepseek-cn` 官方端点默认值 (#1079, #1084)
 - **[wlon](https://github.com/wlon)** — NVIDIA NIM provider API key 优先级诊断 (#1081)
-- **[Horace Liu](https://github.com/liuhq)** — Nix 包支持和安装文档 (#1173)
-- **[jieshu666](https://github.com/jieshu666)** — 终端重绘闪烁修复 (#1563)
-- **[gordonlu](https://github.com/gordonlu)** — Windows Enter / CSI-u 输入修复 (#1612)
-- **[mdrkrg](https://github.com/mdrkrg)** — 首次运行 API key 缺失时的启动崩溃修复 (#1598)
-- **[Aitensa](https://github.com/Aitensa)** — diff 和 pager 输出的 CJK 换行支持 (#1622)
-- **[qiyan233](https://github.com/qiyan233)** — 遗留 DeepSeek CN provider 别名兼容 (#1645)
-- **[zlh124](https://github.com/zlh124)** — WSL2/headless 启动报告和剪贴板初始化修复 (#1772, #1773)
-- **[aboimpinto](https://github.com/aboimpinto)** — Windows alt-screen 日志、Home/End 编辑器，以及运行时日志跟进 (#1774, #1776, #1748, #1749, #1782, #1783)
-- **[LeoLin990405](https://github.com/LeoLin990405)** — provider 模型透传、reasoning 重放、thinking-only turn 和 Windows 引用修复 (#1740, #1743, #1742, #1744)
-- **[nightt5879](https://github.com/nightt5879)** — Ctrl+C 提示恢复修复 (#1764)
-- **[h3c-hexin](https://github.com/h3c-hexin)** — 流式批量工具调用保留和 CLI reasoning-effort 透传 (#1686, #1511)
-- **[hxy91819](https://github.com/hxy91819)** — 工具结果裁剪时的前缀缓存保留 (#1514)
-- **[JiarenWang](https://github.com/JiarenWang)** — Plan 模式只读执行、审批接管优化、Ctrl+H 删除修复和 undo 上下文同步 (#1123, #962, #958, #1150)
-- **[Liu-Vince](https://github.com/Liu-Vince)** — MCP 分页、markdown 缩进保留、zh-Hans i18n 优化和环境变量文档 (#1256, #1179, #1274, #1178)
-- **[linzhiqin2003](https://github.com/linzhiqin2003)** — `--model auto` 成本节约偏好、执行纪律提示和声明式事实记忆指导 (#1385, #1384, #1381)
-- **[lbcheng888](https://github.com/lbcheng888)** — 跨保存/恢复的成本持久化和对话滚动修复 (#1192, #1211)
-- **[pengyou200902](https://github.com/pengyou200902)** — UTF-8 安全记忆截断、截断标记精确化和快捷键文档 (#968, #1122, #1095)
-- **[ChaceLyee2101](https://github.com/ChaceLyee2101)** — 推理 token 成本统计和 zh-Hans 自动 CNY 显示，以及 zh-CN README 同步 (#1505, #1504)
-- **[CrepuscularIRIS](https://github.com/CrepuscularIRIS)** — Termius/SSH 低动画模式和 npx MCP 服务器沙箱修复 (#1479, #1346)
-- **[laoye2020](https://github.com/laoye2020)** — Catppuccin、Tokyo Night、Dracula 和 Gruvbox 主题及 `/theme` 选择器 (#1534)
-- **[punkcanyang](https://github.com/punkcanyang)** — Kitty (OSC 99) 和 Ghostty (OSC 777) 桌面通知支持 (#1426)
-- **[Rene-Kuhm](https://github.com/Rene-Kuhm)** — 西班牙语（es-419）拉丁美洲本地化 (#1452)
-- **[sternelee](https://github.com/sternelee)** — DeepSeek 前缀缓存稳定性追踪 (#1517)
-- **[ComeFromTheMars](https://github.com/ComeFromTheMars)** — Shift+Up/Down 对话滚动快捷键 (#1432)
-- **[sockerch](https://github.com/sockerch)** — 所有斜杠命令的拼音别名 (#1306)
-- **[Apeiron0w0](https://github.com/Apeiron0w0)** — Tabby 终端闪烁循环的 FocusGained 去抖动 (#1560)
-- **[greyfreedom](https://github.com/greyfreedom)** — 跳转到最新对话按钮 (#969)
-- **[SamhandsomeLee](https://github.com/SamhandsomeLee)** — 显式隐藏文件提及补全 (#1270)
-- **[dst1213](https://github.com/dst1213)** — 配额错误 HTTP 400 重试 (#1203)
-- **[fuleinist](https://github.com/fuleinist)** — `--yolo` 标志从 CLI 转发到 TUI (#1233)
-- **[heloanc](https://github.com/heloanc)** — Home/End 键编辑器支持 (#1246)
-- **[jinpengxuan](https://github.com/jinpengxuan)** — 入职期间活动 provider 凭据保留 (#1265)
-- **[lixiasky-back](https://github.com/lixiasky-back)** — 已验证 npm 二进制采用 (#1339)
-- **[J3y0r](https://github.com/J3y0r)** — 工作区切换命令 (#1065)
-- **[KhalidAlnujaidi](https://github.com/KhalidAlnujaidi)** — delegate 技能打包 (#1144)
-- **[Wenjunyun123](https://github.com/Wenjunyun123)** — 文档锚点偏移保留 (#1282)
-- **[whtis](https://github.com/whtis)** — zh-CN README 调度程序路径同步 (#1235)
-- **[aqilaziz](https://github.com/aqilaziz)** — memory 技能链接修复 (#1095)
-- **[wuwuzhijing](https://github.com/wuwuzhijing)** — rsproxy rustup 变通安装文档 (#1011)
-- **[eltociear](https://github.com/eltociear)** — 日语 README 翻译 (#746)
-- **[Ling](https://github.com/LING71671)** — `grep_files` 取消令牌支持和 Ctrl+Z 编辑器草稿恢复 (#1839, #1911)
-- **[Ben Younes](https://github.com/ousamabenyounes)** — Linux Wayland（非 wlroots）剪贴板支持 (#1938)
-- **[Matt Van Horn](https://github.com/mvanhorn)** — Docker 首次运行权限修复和运行时系统提示回归测试 (#1699, #1702)
-- **[Kristopher Clark](https://github.com/krisclarkdev)** — compaction 用户查询保留修复 (#1704)
-- **[tdccccc](https://github.com/tdccccc)** — 编辑器滚动修复和 pager 鼠标滚轮支持 (#1715, #1716)
-- **[LittleBlacky](https://github.com/LittleBlacky)** — provider gated `reasoning_content` 流式修复 (#1680)
-- **[Anaheim](https://github.com/AnaheimEX)** — `rlm_open` 空 source schema 校验报告 (#1712)
-- **[THatch26](https://github.com/THatch26)** — 终端 resize 后翻页修复 (#1724)
-- **[Alvin](https://github.com/alvin1)** — Zed ACP id 兼容性报告 (#1696)
-- **[knqiufan](https://github.com/knqiufan)** — sub-agent 文件写入委派工作 (#1833)
-- **[IIzzaya](https://github.com/IIzzaya)** — slash 补全精确 alias 优先排序想法 (#1811)
-- **[DC](https://github.com/duanchao-lab)** — 终端清理 guard 思路 (#1630)
-- **[imkingjh999](https://github.com/imkingjh999)** — provider/model 切换修复 (#1642)
-- **[Photo](https://github.com/eng2007)** — provider-aware `/model` picker catalog 工作 (#1201)
-- **[chennest](https://github.com/chennest)** — diagnostics schema 报告 (#1685)
-- **[kunpeng-ai-lab](https://github.com/kunpeng-ai-lab)** — Windows 编辑器滚动修复 (#1578)
-- **[WuMing](https://github.com/asdfg314284230)** — Windows PowerShell 闪烁修复 (#1591)
-- **[maker316](https://github.com/maker316)** — LoopGuard/checklist 循环报告 (#1574)
-- **[lalala](https://github.com/lalala-233)** — approval denial 回归报告 (#1617)
-- **[muyuliyan](https://github.com/muyuliyan)** — `pandoc_convert` 校验修复 (#1523)
-- **[czf0718](https://github.com/czf0718)** — resize 和 turn-completion 闪烁修复 (#1537)
-- **[MeAiRobot](https://github.com/MeAiRobot)** — toast 覆盖编辑器输入的修复 (#1485)
-- **[tiger-dog](https://github.com/tiger-dog)** — approval modal 折叠和 markdown identifier 修复 (#1455)
-- **[MMMarcinho](https://github.com/MMMarcinho)** — opt-in `image_analyze` 视觉工具 (#1467)
-- **[lucaszhu-hue](https://github.com/lucaszhu-hue)** — AtlasCloud provider 集成 (#1436)
-- **[sandofree](https://github.com/sandofree)** — Tavily 和 Bocha `web_search` 后端 (#1294)
-- **[zhuangbiaowei](https://github.com/zhuangbiaowei)** — `/change` release notes 命令 (#1416)
-- **[NorethSea](https://github.com/NorethSea)** — updater 同步刷新 companion binary 的修复 (#1492)
-- **[Jianfengwu2024](https://github.com/Jianfengwu2024)** — Windows MSVC toolchain 环境保留 (#1487)
-- **[Fire-dtx](https://github.com/Fire-dtx)** — npm postinstall 可恢复性工作 (#1059)
-- **[oooyuy92](https://github.com/oooyuy92)** — 长会话配色可读性报告 (#1070, #936)
-- **[qinxianyuzou](https://github.com/qinxianyuzou)** — zh-Hans destructive approval 文案 (#1087, #1091)
-- **[tyouter](https://github.com/tyouter)** — session title/history preview 清理 (#1510)
-- **[xulongzhe](https://github.com/xulongzhe)** — issue template 和 vision boundary follow-up (#1530, #1544)
-- **[YaYII](https://github.com/YaYII)** — trusted media path 工作 (#1462)
-- **[47Cid](https://github.com/47Cid)** 和 **[Jafar Akhondali](https://github.com/JafarAkhondali)** — 负责任安全披露和加固报告
+- **[donglovejava](https://github.com/donglovejava)** — paste @file 整合、CJK panic 修复、用户反馈、RLM 路由、edit_file 重试 (#2154–#2168)
+- **[encyc](https://github.com/encyc)** — session token 分解显示和 `/status` (#2152)
+- **[saieswar237](https://github.com/saieswar237)** — 审查流程文档 (#2178)
+- **[sximelon](https://github.com/sximelon)** — paste Enter 抑制、键盘处理提取 (#2174, #2042)
+- **[nanookclaw](https://github.com/nanookclaw)** — search provider 显示在 doctor (#2135)
+- **[Sskift](https://github.com/Sskift)** — CLI 默认环境变量覆盖防止 (#2119)
+- **[xin1104](https://github.com/xin1104)** — Homebrew codewhale 二进制安装 (#2105)
+- **[mrluanma](https://github.com/mrluanma)** — Metaso 搜索提供商 (#2059)
+- **[Lellansin](https://github.com/Lellansin)** — 主目录下跳过配置合并 (#2055)
+- **[zhuangbiaowei](https://github.com/zhuangbiaowei)** — 更新发布渠道 (#2145)
 
 ---
 
diff --git a/assets/screenshot.png b/assets/screenshot.png
index 4ddd4850..e9c79fee 100644
Binary files a/assets/screenshot.png and b/assets/screenshot.png differ
diff --git a/config.example.toml b/config.example.toml
index 87af1a8e..46f44aa4 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -13,11 +13,12 @@
 # `[providers.*]` sections near the bottom of
 # this file — keeping both stored at once means `/provider deepseek` and
 # `/provider nvidia-nim` (or `--provider openai`, `--provider wanjie-ark`,
-# `--provider fireworks`, `/provider sglang`, `/provider vllm`, `/provider ollama`)
-# toggle without having to re-enter keys. Top-level `api_key` / `base_url` are
+# `--provider volcengine`, `--provider xiaomi-mimo`, `--provider fireworks`, `/provider sglang`,
+# `/provider vllm`, `/provider ollama`) toggle without having to re-enter keys.
+# Top-level `api_key` / `base_url` are
 # still read as DeepSeek defaults when `[providers.deepseek]` is absent
 # (backward compatibility).
-provider = "deepseek" # deepseek | deepseek-cn | nvidia-nim | openai | atlascloud | wanjie-ark | openrouter | novita | fireworks | sglang | vllm | ollama
+provider = "deepseek" # deepseek | deepseek-cn | nvidia-nim | openai | atlascloud | wanjie-ark | volcengine | openrouter | xiaomi-mimo | novita | fireworks | sglang | vllm | ollama
 api_key = "YOUR_DEEPSEEK_API_KEY" # must be non-empty
 base_url = "https://api.deepseek.com/beta"
 # provider = "deepseek-cn"                       # legacy alias (official host is still https://api.deepseek.com)
@@ -37,6 +38,7 @@ base_url = "https://api.deepseek.com/beta"
 #   gpt-4.1                         — default generic OpenAI-compatible model ID
 #   deepseek-ai/deepseek-v4-flash   — default AtlasCloud model ID
 #   deepseek-reasoner               — default Wanjie Ark model ID
+#   mimo-v2.5-pro                   — default Xiaomi MiMo model ID
 #   accounts/fireworks/models/deepseek-v4-pro — Fireworks AI Pro model ID
 #   deepseek-ai/DeepSeek-V4-Pro    — SGLang self-hosted Pro model ID
 #   deepseek-ai/DeepSeek-V4-Flash  — SGLang self-hosted Flash model ID
@@ -97,6 +99,12 @@ memory_path = "~/.deepseek/memory.md"
 # Parsed but currently unused (reserved for future versions):
 # tools_file = "./tools.json"
 
+# Native tool catalog controls (#2076). By default only the core tool surface
+# is loaded into the model context; less common native tools are discoverable
+# through ToolSearch and loaded on first use.
+# [tools]
+# always_load = ["git_show", "notify"]
+
 # ─────────────────────────────────────────────────────────────────────────────────
 # Security
 # ─────────────────────────────────────────────────────────────────────────────────
@@ -131,6 +139,21 @@ sandbox_mode = "workspace-write" # read-only | workspace-write | danger-full-acc
 # The backend uses a 30-second HTTP timeout. Background, interactive, and
 # TTY modes are not supported with external backends — all commands run
 # synchronously via HTTP.
+# ─────────────────────────────────────────────────────────────────────────────────
+# Bubblewrap (Linux only, additional filesystem isolation)
+# ─────────────────────────────────────────────────────────────────────────────────
+# When set to true and `/usr/bin/bwrap` is present, exec_shell commands are
+# routed through bubblewrap instead of relying solely on Landlock. Bubblewrap
+# creates a read-only view of the root filesystem with write access limited to
+# the working directory. Install separately:
+#
+#   Ubuntu/Debian:  apt install bubblewrap
+#   Fedora:         dnf install bubblewrap
+#   Arch:           pacman -S bubblewrap
+#
+# prefer_bwrap = false  # default — use Landlock only
+#
+# Env override: DEEPSEEK_PREFER_BWRAP=true
 
 # auto_allow entries match by command prefix, not raw string.
 # See command_safety.rs for the prefix dictionary.
@@ -165,17 +188,27 @@ max_subagents = 10 # optional (1-20)
 #   OpenAI-compatible: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL
 #   Wanjie Ark: WANJIE_ARK_API_KEY (or WANJIE_API_KEY), WANJIE_ARK_BASE_URL, WANJIE_ARK_MODEL
 #   OpenRouter: OPENROUTER_API_KEY, OPENROUTER_BASE_URL, OPENROUTER_MODEL
+#   Xiaomi MiMo: XIAOMI_MIMO_API_KEY (or MIMO_API_KEY), XIAOMI_MIMO_BASE_URL, XIAOMI_MIMO_MODEL
 #   Novita:     NOVITA_API_KEY, NOVITA_BASE_URL, NOVITA_MODEL
 #   Fireworks:  FIREWORKS_API_KEY, FIREWORKS_BASE_URL
 #   SGLang:    SGLANG_BASE_URL, SGLANG_MODEL, optional SGLANG_API_KEY
 #   vLLM:      VLLM_BASE_URL, VLLM_MODEL, optional VLLM_API_KEY
 #   Ollama:    OLLAMA_BASE_URL, OLLAMA_MODEL, optional OLLAMA_API_KEY
+#
+# Custom DeepSeek-compatible APIs usually do not need a new provider table:
+# set `provider = "deepseek"` and override [providers.deepseek].base_url/model.
+# For generic OpenAI-compatible gateways, use `provider = "openai"` and the
+# [providers.openai] table below. Keep provider/api_key/base_url in user config
+# or environment variables; project overlays are not allowed to set them.
 
 # DeepSeek Platform (https://platform.deepseek.com)
 [providers.deepseek]
 # api_key = "YOUR_DEEPSEEK_API_KEY"
 # base_url = "https://api.deepseek.com/beta"
 # model = "deepseek-v4-pro"
+# Custom DeepSeek-compatible example:
+# base_url = "https://your-provider.example/v1"
+# model = "deepseek-ai/DeepSeek-V4-Pro"
 # http_headers = { "X-Model-Provider-Id" = "your-model-provider" } # optional custom request headers
 
 # NVIDIA NIM-hosted DeepSeek V4 (https://build.nvidia.com)
@@ -192,6 +225,9 @@ max_subagents = 10 # optional (1-20)
 # api_key = "YOUR_OPENAI_COMPATIBLE_API_KEY"
 # base_url = "https://api.openai.com/v1"
 # model = "gpt-4.1"
+# Gateway example:
+# base_url = "https://gateway.example/v1"
+# model = "your-deepseek-compatible-model"
 
 # AtlasCloud OpenAI-compatible endpoint (https://www.atlascloud.ai/docs/models/llm)
 [providers.atlascloud]
@@ -205,12 +241,24 @@ max_subagents = 10 # optional (1-20)
 # base_url = "https://maas-openapi.wanjiedata.com/api/v1"
 # model = "deepseek-reasoner"                # or the exact model ID enabled on your Wanjie account
 
+# Volcengine / Volcano Engine Ark Coding API
+[providers.volcengine]
+# api_key = "YOUR_VOLCENGINE_API_KEY"
+# base_url = "https://ark.cn-beijing.volces.com/api/coding/v3"
+# model = "DeepSeek-V4-Pro"                  # or DeepSeek-V4-Flash
+
 # OpenRouter — multi-provider gateway (https://openrouter.ai)
 [providers.openrouter]
 # api_key = "YOUR_OPENROUTER_API_KEY"
 # base_url = "https://openrouter.ai/api/v1"
 # model = "deepseek/deepseek-v4-pro"         # or deepseek/deepseek-v4-flash
 
+# Xiaomi MiMo OpenAI-compatible endpoint (https://platform.xiaomimimo.com)
+[providers.xiaomi_mimo]
+# api_key = "YOUR_XIAOMI_MIMO_API_KEY"
+# base_url = "https://api.xiaomimimo.com/v1"
+# model = "mimo-v2.5-pro"
+
 # Novita AI-hosted inference (https://novita.ai)
 [providers.novita]
 # api_key = "YOUR_NOVITA_API_KEY"
@@ -244,23 +292,29 @@ max_subagents = 10 # optional (1-20)
 # ─────────────────────────────────────────────────────────────────────────────────
 # Web Search Provider
 # ─────────────────────────────────────────────────────────────────────────────────
-# Choose which backend `web_search` uses. Default is Bing HTML scraping — no
-# API key needed. DuckDuckGo remains selectable and still falls back to Bing
-# when its HTML endpoint returns a bot challenge or no parseable results.
-# Switch to Tavily or Bocha for reliable search in mainland China.
+# Choose which backend `web_search` uses. Default is DuckDuckGo HTML scraping
+# with Bing fallback — no API key needed. Bing remains selectable for users who
+# explicitly prefer it. Switch to Tavily, Bocha, Metaso, or Baidu for
+# API-backed search.
 #
 # [search]
-# provider = "bing"         # bing | duckduckgo | tavily | bocha
+# provider = "duckduckgo"  # duckduckgo | bing | tavily | bocha | metaso | baidu
 #                            # duckduckgo: HTML scrape with Bing fallback
-#                            # tavily: https://tavily.com — AI search, needs api_key
-#                            # bocha:  https://bochaai.com — 博查AI搜索，国内友好，需api_key
-# api_key = "tvly-YOUR_KEY"  # required for tavily and bocha
-#                            # WARNING: treat config.toml like a secret file when
-#                            # storing API keys. Use env vars or `auth set` instead.
+#                            # bing:       HTML scrape, no API key
+#                            # tavily:     https://tavily.com — AI search, needs api_key
+#                            # bocha:      https://bochaai.com — 博查AI搜索，国内友好，需api_key
+#                            # metaso:     https://metaso.cn — 秘塔AI搜索，每天 100 次免费
+#                            #             设置 METASO_API_KEY 或 [search] api_key 可提升额度
+#                            # baidu:      百度 AI Search via qianfan.baidubce.com，需 api_key
+# api_key = "YOUR_SEARCH_KEY" # required for tavily, bocha, and baidu; optional for metaso
+#                             # WARNING: treat config.toml like a secret file when
+#                             # storing API keys. Prefer env vars for local smoke tests.
 #
 # Env-var overrides:
 #   DEEPSEEK_SEARCH_PROVIDER → search.provider
 #   DEEPSEEK_SEARCH_API_KEY  → search.api_key
+#   METASO_API_KEY           → metaso key fallback
+#   BAIDU_SEARCH_API_KEY     → baidu key fallback
 
 # ─────────────────────────────────────────────────────────────────────────────────
 # Network Policy (#135)
@@ -345,6 +399,11 @@ exec_policy = true
 # model = "gemini-3.1-flash-lite-preview"  # Required: vision-capable model ID
 # api_key = "YOUR_API_KEY"                 # Optional: defaults to main api_key
 # base_url = "https://generativelanguage.googleapis.com/v1beta/openai/"  # Optional
+#
+# Xiaomi MiMo image understanding can be configured through the same tool:
+# model = "mimo-v2.5"
+# api_key = "YOUR_XIAOMI_MIMO_API_KEY"
+# base_url = "https://api.xiaomimimo.com/v1"
 
 # ─────────────────────────────────────────────────────────────────────────────────
 # Retry Configuration
@@ -508,8 +567,13 @@ default_text_model = "deepseek-ai/deepseek-v4-pro"
 #   go         → gopls serve
 #   python     → pyright-langserver --stdio
 #   typescript → typescript-language-server --stdio
+#   java       → jdtls
+#   vue        → vue-language-server --stdio
 #   c, cpp     → clangd
 #
+# Java support uses Eclipse JDT LS via the `jdtls` command. IntelliJ IDEA is
+# not required, and installing IntelliJ IDEA alone does not install `jdtls`.
+#
 # Override the defaults via the `servers` table below.
 [lsp]
 # enabled = true
@@ -519,6 +583,8 @@ default_text_model = "deepseek-ai/deepseek-v4-pro"
 # [lsp.servers]
 # rust = ["rust-analyzer"]
 # go = ["gopls", "serve"]
+# java = ["jdtls"]
+# vue = ["vue-language-server", "--stdio"]
 
 # ─────────────────────────────────────────────────────────────────────────────────
 # Hooks (optional)
diff --git a/crates/agent/Cargo.toml b/crates/agent/Cargo.toml
index c6d4fd3f..4f98a69c 100644
--- a/crates/agent/Cargo.toml
+++ b/crates/agent/Cargo.toml
@@ -7,5 +7,5 @@ repository.workspace = true
 description = "Model/provider registry and fallback strategy for DeepSeek workspace architecture"
 
 [dependencies]
-codewhale-config = { path = "../config", version = "0.8.44" }
+codewhale-config = { path = "../config", version = "0.8.46" }
 serde.workspace = true
diff --git a/crates/agent/src/lib.rs b/crates/agent/src/lib.rs
index 928973c0..261d51ad 100644
--- a/crates/agent/src/lib.rs
+++ b/crates/agent/src/lib.rs
@@ -74,18 +74,18 @@ impl Default for ModelRegistry {
                 supports_reasoning: true,
             },
             ModelInfo {
-                id: "gpt-4.1".to_string(),
+                id: "deepseek-v4-pro".to_string(),
                 provider: ProviderKind::Openai,
-                aliases: vec!["gpt4.1".to_string(), "gpt-4o".to_string()],
+                aliases: vec!["openai-compatible-deepseek-v4-pro".to_string()],
                 supports_tools: true,
                 supports_reasoning: true,
             },
             ModelInfo {
-                id: "gpt-4.1-mini".to_string(),
+                id: "deepseek-v4-flash".to_string(),
                 provider: ProviderKind::Openai,
-                aliases: vec!["gpt-4o-mini".to_string()],
+                aliases: vec!["openai-compatible-deepseek-v4-flash".to_string()],
                 supports_tools: true,
-                supports_reasoning: false,
+                supports_reasoning: true,
             },
             ModelInfo {
                 id: "deepseek-reasoner".to_string(),
@@ -97,6 +97,29 @@ impl Default for ModelRegistry {
                 supports_tools: true,
                 supports_reasoning: true,
             },
+            ModelInfo {
+                id: "DeepSeek-V4-Pro".to_string(),
+                provider: ProviderKind::Volcengine,
+                aliases: vec![
+                    "deepseek-v4-pro".to_string(),
+                    "volcengine-deepseek-v4-pro".to_string(),
+                    "ark-deepseek-v4-pro".to_string(),
+                ],
+                supports_tools: true,
+                supports_reasoning: true,
+            },
+            ModelInfo {
+                id: "DeepSeek-V4-Flash".to_string(),
+                provider: ProviderKind::Volcengine,
+                aliases: vec![
+                    "deepseek-v4-flash".to_string(),
+                    "deepseek-chat".to_string(),
+                    "volcengine-deepseek-v4-flash".to_string(),
+                    "ark-deepseek-v4-flash".to_string(),
+                ],
+                supports_tools: true,
+                supports_reasoning: true,
+            },
             ModelInfo {
                 id: "deepseek/deepseek-v4-pro".to_string(),
                 provider: ProviderKind::Openrouter,
@@ -119,6 +142,20 @@ impl Default for ModelRegistry {
                 supports_tools: true,
                 supports_reasoning: true,
             },
+            ModelInfo {
+                id: "mimo-v2.5-pro".to_string(),
+                provider: ProviderKind::XiaomiMimo,
+                aliases: vec!["mimo".to_string()],
+                supports_tools: true,
+                supports_reasoning: true,
+            },
+            ModelInfo {
+                id: "mimo-v2.5".to_string(),
+                provider: ProviderKind::XiaomiMimo,
+                aliases: vec!["xiaomi-mimo-v2.5".to_string()],
+                supports_tools: true,
+                supports_reasoning: true,
+            },
             ModelInfo {
                 id: "deepseek/deepseek-v4-pro".to_string(),
                 provider: ProviderKind::Novita,
@@ -151,6 +188,17 @@ impl Default for ModelRegistry {
                 supports_tools: true,
                 supports_reasoning: true,
             },
+            ModelInfo {
+                id: "kimi-k2.6".to_string(),
+                provider: ProviderKind::Moonshot,
+                aliases: vec![
+                    "kimi".to_string(),
+                    "kimi-k2".to_string(),
+                    "moonshot-kimi-k2.6".to_string(),
+                ],
+                supports_tools: true,
+                supports_reasoning: true,
+            },
             ModelInfo {
                 id: "deepseek-ai/DeepSeek-V4-Pro".to_string(),
                 provider: ProviderKind::Sglang,
@@ -258,7 +306,7 @@ impl ModelRegistry {
             {
                 return ModelResolution {
                     requested: Some(name.to_string()),
-                    resolved: preserve_requested_model_id_case(model, name),
+                    resolved: model,
                     used_fallback: false,
                     fallback_chain,
                 };
@@ -371,6 +419,16 @@ mod tests {
         assert_eq!(resolved.resolved.id, "deepseek/deepseek-v4-pro");
     }
 
+    #[test]
+    fn xiaomi_mimo_default_uses_canonical_model_id() {
+        let registry = ModelRegistry::default();
+        let resolved = registry.resolve(None, Some(ProviderKind::XiaomiMimo));
+
+        assert_eq!(resolved.resolved.provider, ProviderKind::XiaomiMimo);
+        assert_eq!(resolved.resolved.id, "mimo-v2.5-pro");
+        assert!(resolved.resolved.supports_reasoning);
+    }
+
     #[test]
     fn wanjie_ark_default_uses_reasoner_model_id() {
         let registry = ModelRegistry::default();
@@ -486,12 +544,13 @@ mod tests {
     }
 
     #[test]
-    fn preserves_requested_model_casing_with_provider_hint() {
+    fn registry_casing_takes_priority_over_requested_casing_with_provider_hint() {
         let registry = ModelRegistry::default();
         let resolved = registry.resolve(Some("DeepSeek-V4-Pro"), Some(ProviderKind::Deepseek));
 
         assert_eq!(resolved.resolved.provider, ProviderKind::Deepseek);
-        assert_eq!(resolved.resolved.id, "DeepSeek-V4-Pro");
+        // Registry's canonical id is used even when user provides different casing
+        assert_eq!(resolved.resolved.id, "deepseek-v4-pro");
     }
 
     #[test]
diff --git a/crates/app-server/Cargo.toml b/crates/app-server/Cargo.toml
index dc87c887..09dd8643 100644
--- a/crates/app-server/Cargo.toml
+++ b/crates/app-server/Cargo.toml
@@ -10,16 +10,21 @@ description = "Codex-style app-server transport for DeepSeek workspace architect
 anyhow.workspace = true
 axum.workspace = true
 clap.workspace = true
-codewhale-agent = { path = "../agent", version = "0.8.44" }
-codewhale-config = { path = "../config", version = "0.8.44" }
-codewhale-core = { path = "../core", version = "0.8.44" }
-codewhale-execpolicy = { path = "../execpolicy", version = "0.8.44" }
-codewhale-hooks = { path = "../hooks", version = "0.8.44" }
-codewhale-mcp = { path = "../mcp", version = "0.8.44" }
-codewhale-protocol = { path = "../protocol", version = "0.8.44" }
-codewhale-state = { path = "../state", version = "0.8.44" }
-codewhale-tools = { path = "../tools", version = "0.8.44" }
+codewhale-agent = { path = "../agent", version = "0.8.46" }
+codewhale-config = { path = "../config", version = "0.8.46" }
+codewhale-core = { path = "../core", version = "0.8.46" }
+codewhale-execpolicy = { path = "../execpolicy", version = "0.8.46" }
+codewhale-hooks = { path = "../hooks", version = "0.8.46" }
+codewhale-mcp = { path = "../mcp", version = "0.8.46" }
+codewhale-protocol = { path = "../protocol", version = "0.8.46" }
+codewhale-state = { path = "../state", version = "0.8.46" }
+codewhale-tools = { path = "../tools", version = "0.8.46" }
 serde.workspace = true
 serde_json.workspace = true
 tokio.workspace = true
 tower-http.workspace = true
+uuid.workspace = true
+
+[dev-dependencies]
+tempfile = "3.16"
+tower = "0.5"
diff --git a/crates/app-server/src/lib.rs b/crates/app-server/src/lib.rs
index e580ed32..a9fe4399 100644
--- a/crates/app-server/src/lib.rs
+++ b/crates/app-server/src/lib.rs
@@ -2,8 +2,11 @@ use std::net::SocketAddr;
 use std::path::PathBuf;
 use std::sync::Arc;
 
-use anyhow::Result;
-use axum::extract::State;
+use anyhow::{Result, bail};
+use axum::extract::{Request, State};
+use axum::http::{HeaderValue, Method, StatusCode, header};
+use axum::middleware::{self, Next};
+use axum::response::{IntoResponse, Response};
 use axum::routing::{get, post};
 use axum::{Json, Router};
 use codewhale_agent::ModelRegistry;
@@ -23,11 +26,25 @@ use serde_json::{Value, json};
 use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 use tokio::sync::{Mutex, RwLock};
 use tower_http::cors::CorsLayer;
+use uuid::Uuid;
+
+const DEFAULT_CORS_ORIGINS: &[&str] = &[
+    "http://localhost",
+    "http://localhost:1420",
+    "http://localhost:3000",
+    "http://localhost:5173",
+    "http://127.0.0.1",
+    "http://127.0.0.1:1420",
+    "tauri://localhost",
+];
 
 #[derive(Debug, Clone)]
 pub struct AppServerOptions {
     pub listen: SocketAddr,
     pub config_path: Option<PathBuf>,
+    pub auth_token: Option<String>,
+    pub insecure_no_auth: bool,
+    pub cors_origins: Vec<String>,
 }
 
 #[derive(Clone)]
@@ -36,6 +53,7 @@ struct AppState {
     config: Arc<RwLock<codewhale_config::ConfigToml>>,
     runtime: Arc<Mutex<Runtime>>,
     registry: ModelRegistry,
+    auth_token: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -69,6 +87,12 @@ struct StdioDispatchResult {
     should_exit: bool,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum AppTransport {
+    Http,
+    Stdio,
+}
+
 #[derive(Debug, Deserialize)]
 struct ConfigGetParams {
     key: String,
@@ -92,26 +116,37 @@ struct ThreadMessageParams {
 }
 
 pub async fn run(options: AppServerOptions) -> Result<()> {
-    let state = build_state(options.config_path.clone())?;
-
-    let app = Router::new()
-        .route("/healthz", get(healthz))
-        .route("/thread", post(thread_handler))
-        .route("/app", post(app_handler))
-        .route("/prompt", post(prompt_handler))
-        .route("/tool", post(tool_handler))
-        .route("/jobs", get(jobs_handler))
-        .route("/mcp/startup", post(mcp_startup_handler))
-        .layer(CorsLayer::permissive())
-        .with_state(state);
+    let auth_token = resolve_auth_token(&options)?;
+    let state = build_state(options.config_path.clone(), auth_token)?;
+    let app = app_router(state, &options.cors_origins);
 
     let listener = tokio::net::TcpListener::bind(options.listen).await?;
     axum::serve(listener, app).await?;
     Ok(())
 }
 
+fn app_router(state: AppState, cors_origins: &[String]) -> Router {
+    let protected_routes = Router::new()
+        .route("/thread", post(thread_handler))
+        .route("/app", post(app_handler))
+        .route("/prompt", post(prompt_handler))
+        .route("/tool", post(tool_handler))
+        .route("/jobs", get(jobs_handler))
+        .route("/mcp/startup", post(mcp_startup_handler))
+        .route_layer(middleware::from_fn_with_state(
+            state.clone(),
+            require_app_server_token,
+        ));
+
+    Router::new()
+        .route("/healthz", get(healthz))
+        .merge(protected_routes)
+        .layer(cors_layer(cors_origins))
+        .with_state(state)
+}
+
 pub async fn run_stdio(config_path: Option<PathBuf>) -> Result<()> {
-    let state = build_state(config_path)?;
+    let state = build_state(config_path, None)?;
     let stdin = tokio::io::stdin();
     let stdout = tokio::io::stdout();
     let mut reader = BufReader::new(stdin).lines();
@@ -258,10 +293,10 @@ async fn app_handler(
     State(state): State<AppState>,
     Json(req): Json<AppRequest>,
 ) -> Json<AppResponse> {
-    Json(process_app_request(&state, req).await)
+    Json(process_app_request(&state, req, AppTransport::Http).await)
 }
 
-fn build_state(config_path: Option<PathBuf>) -> Result<AppState> {
+fn build_state(config_path: Option<PathBuf>, auth_token: Option<String>) -> Result<AppState> {
     let store = ConfigStore::load(config_path.clone())?;
     let config = store.config.clone();
     let registry = ModelRegistry::default();
@@ -294,9 +329,95 @@ fn build_state(config_path: Option<PathBuf>) -> Result<AppState> {
         config: Arc::new(RwLock::new(config)),
         runtime: Arc::new(Mutex::new(runtime)),
         registry,
+        auth_token,
     })
 }
 
+fn resolve_auth_token(options: &AppServerOptions) -> Result<Option<String>> {
+    let configured = options.auth_token.as_ref().map(|token| token.trim());
+    if let Some(token) = configured
+        && token.is_empty()
+    {
+        bail!("app-server auth token cannot be empty");
+    }
+
+    if options.insecure_no_auth {
+        if !options.listen.ip().is_loopback() {
+            bail!("refusing unauthenticated app-server bind on non-loopback address");
+        }
+        eprintln!("warning: app-server HTTP auth disabled by --insecure-no-auth");
+        return Ok(None);
+    }
+
+    let token = configured
+        .map(str::to_string)
+        .unwrap_or_else(|| format!("cwapp_{}", Uuid::new_v4().simple()));
+    if options.auth_token.is_some() {
+        eprintln!("app-server auth: bearer token required for HTTP routes.");
+    } else {
+        eprintln!("app-server auth: generated bearer token for this process.");
+        eprintln!("  Authorization: Bearer {token}");
+        eprintln!("  Pass --auth-token or set CODEWHALE_APP_SERVER_TOKEN for a stable token.");
+    }
+    Ok(Some(token))
+}
+
+fn cors_layer(extra_origins: &[String]) -> CorsLayer {
+    let mut origins: Vec<HeaderValue> = DEFAULT_CORS_ORIGINS
+        .iter()
+        .filter_map(|origin| HeaderValue::from_str(origin).ok())
+        .collect();
+    for raw in extra_origins {
+        let trimmed = raw.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        match HeaderValue::from_str(trimmed) {
+            Ok(value) if !origins.contains(&value) => origins.push(value),
+            Ok(_) => {}
+            Err(err) => {
+                eprintln!("warning: ignoring invalid app-server CORS origin `{trimmed}`: {err}")
+            }
+        }
+    }
+
+    CorsLayer::new()
+        .allow_origin(origins)
+        .allow_methods([Method::GET, Method::POST, Method::OPTIONS])
+        .allow_headers([header::AUTHORIZATION, header::CONTENT_TYPE])
+}
+
+async fn require_app_server_token(
+    State(state): State<AppState>,
+    req: Request,
+    next: Next,
+) -> Response {
+    let Some(expected) = state.auth_token.as_deref() else {
+        return next.run(req).await;
+    };
+    let authorized = req
+        .headers()
+        .get(header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .and_then(|raw| raw.strip_prefix("Bearer "))
+        .is_some_and(|token| token == expected);
+
+    if authorized {
+        next.run(req).await
+    } else {
+        (
+            StatusCode::UNAUTHORIZED,
+            Json(json!({
+                "error": {
+                    "message": "app-server bearer token required",
+                    "status": StatusCode::UNAUTHORIZED.as_u16(),
+                }
+            })),
+        )
+            .into_response()
+    }
+}
+
 fn params_or_object(params: Value) -> Value {
     if params.is_null() { json!({}) } else { params }
 }
@@ -585,7 +706,8 @@ async fn dispatch_stdio_request(
             }
         }
         "app/capabilities" => {
-            let response = process_app_request(state, AppRequest::Capabilities).await;
+            let response =
+                process_app_request(state, AppRequest::Capabilities, AppTransport::Stdio).await;
             StdioDispatchResult {
                 result: serde_json::to_value(response)
                     .map_err(|err| JsonRpcError::internal(err.to_string()))?,
@@ -594,7 +716,7 @@ async fn dispatch_stdio_request(
         }
         "app/request" => {
             let request: AppRequest = parse_params(params)?;
-            let response = process_app_request(state, request).await;
+            let response = process_app_request(state, request, AppTransport::Stdio).await;
             StdioDispatchResult {
                 result: serde_json::to_value(response)
                     .map_err(|err| JsonRpcError::internal(err.to_string()))?,
@@ -603,8 +725,12 @@ async fn dispatch_stdio_request(
         }
         "app/config/get" => {
             let parsed: ConfigGetParams = parse_params(params_or_object(params))?;
-            let response =
-                process_app_request(state, AppRequest::ConfigGet { key: parsed.key }).await;
+            let response = process_app_request(
+                state,
+                AppRequest::ConfigGet { key: parsed.key },
+                AppTransport::Stdio,
+            )
+            .await;
             StdioDispatchResult {
                 result: serde_json::to_value(response)
                     .map_err(|err| JsonRpcError::internal(err.to_string()))?,
@@ -619,6 +745,7 @@ async fn dispatch_stdio_request(
                     key: parsed.key,
                     value: parsed.value,
                 },
+                AppTransport::Stdio,
             )
             .await;
             StdioDispatchResult {
@@ -629,8 +756,12 @@ async fn dispatch_stdio_request(
         }
         "app/config/unset" => {
             let parsed: ConfigGetParams = parse_params(params_or_object(params))?;
-            let response =
-                process_app_request(state, AppRequest::ConfigUnset { key: parsed.key }).await;
+            let response = process_app_request(
+                state,
+                AppRequest::ConfigUnset { key: parsed.key },
+                AppTransport::Stdio,
+            )
+            .await;
             StdioDispatchResult {
                 result: serde_json::to_value(response)
                     .map_err(|err| JsonRpcError::internal(err.to_string()))?,
@@ -638,7 +769,8 @@ async fn dispatch_stdio_request(
             }
         }
         "app/config/list" => {
-            let response = process_app_request(state, AppRequest::ConfigList).await;
+            let response =
+                process_app_request(state, AppRequest::ConfigList, AppTransport::Stdio).await;
             StdioDispatchResult {
                 result: serde_json::to_value(response)
                     .map_err(|err| JsonRpcError::internal(err.to_string()))?,
@@ -646,7 +778,8 @@ async fn dispatch_stdio_request(
             }
         }
         "app/models" => {
-            let response = process_app_request(state, AppRequest::Models).await;
+            let response =
+                process_app_request(state, AppRequest::Models, AppTransport::Stdio).await;
             StdioDispatchResult {
                 result: serde_json::to_value(response)
                     .map_err(|err| JsonRpcError::internal(err.to_string()))?,
@@ -654,7 +787,8 @@ async fn dispatch_stdio_request(
             }
         }
         "app/thread_loaded_list" | "app/thread-loaded-list" => {
-            let response = process_app_request(state, AppRequest::ThreadLoadedList).await;
+            let response =
+                process_app_request(state, AppRequest::ThreadLoadedList, AppTransport::Stdio).await;
             StdioDispatchResult {
                 result: serde_json::to_value(response)
                     .map_err(|err| JsonRpcError::internal(err.to_string()))?,
@@ -685,7 +819,11 @@ async fn dispatch_stdio_request(
     Ok(outcome)
 }
 
-async fn process_app_request(state: &AppState, req: AppRequest) -> AppResponse {
+async fn process_app_request(
+    state: &AppState,
+    req: AppRequest,
+    transport: AppTransport,
+) -> AppResponse {
     match req {
         AppRequest::Capabilities => AppResponse {
             ok: true,
@@ -700,9 +838,13 @@ async fn process_app_request(state: &AppState, req: AppRequest) -> AppResponse {
         },
         AppRequest::ConfigGet { key } => {
             let cfg = state.config.read().await;
+            let value = match transport {
+                AppTransport::Http => cfg.get_display_value(&key),
+                AppTransport::Stdio => cfg.get_value(&key),
+            };
             AppResponse {
                 ok: true,
-                data: json!({ "key": key, "value": cfg.get_value(&key) }),
+                data: json!({ "key": key, "value": value }),
                 events: Vec::new(),
             }
         }
@@ -781,3 +923,141 @@ async fn persist_config(state: &AppState, config: codewhale_config::ConfigToml)
     store.config = config;
     store.save()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::body::{Body, to_bytes};
+    use codewhale_protocol::AppRequest;
+    use std::fs;
+    use tower::ServiceExt;
+
+    fn app_with_config(auth_token: Option<&str>) -> (Router, tempfile::TempDir) {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let config_path = tmp.path().join("config.toml");
+        fs::write(&config_path, "api_key = \"sk-deepseek-secret\"\n").expect("write config");
+        let state = build_state(
+            Some(config_path),
+            auth_token.map(std::string::ToString::to_string),
+        )
+        .expect("state");
+        (app_router(state, &[]), tmp)
+    }
+
+    async fn response_body_json(response: Response) -> Value {
+        let bytes = to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("body bytes");
+        serde_json::from_slice(&bytes).expect("json response")
+    }
+
+    #[tokio::test]
+    async fn http_app_routes_require_bearer_token_when_auth_enabled() {
+        let (app, _tmp) = app_with_config(Some("test-token"));
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method(Method::POST)
+                    .uri("/app")
+                    .header(header::CONTENT_TYPE, "application/json")
+                    .body(Body::from(
+                        serde_json::to_vec(&AppRequest::ConfigGet {
+                            key: "api_key".to_string(),
+                        })
+                        .expect("request json"),
+                    ))
+                    .expect("request"),
+            )
+            .await
+            .expect("response");
+
+        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+    }
+
+    #[tokio::test]
+    async fn http_config_get_redacts_sensitive_values_after_auth() {
+        let (app, _tmp) = app_with_config(Some("test-token"));
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method(Method::POST)
+                    .uri("/app")
+                    .header(header::AUTHORIZATION, "Bearer test-token")
+                    .header(header::CONTENT_TYPE, "application/json")
+                    .body(Body::from(
+                        serde_json::to_vec(&AppRequest::ConfigGet {
+                            key: "api_key".to_string(),
+                        })
+                        .expect("request json"),
+                    ))
+                    .expect("request"),
+            )
+            .await
+            .expect("response");
+
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = response_body_json(response).await;
+        assert_eq!(body["data"]["value"], "sk-d***cret");
+    }
+
+    #[tokio::test]
+    async fn cors_does_not_allow_arbitrary_origins() {
+        let (app, _tmp) = app_with_config(Some("test-token"));
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method(Method::GET)
+                    .uri("/healthz")
+                    .header(header::ORIGIN, "https://attacker.example")
+                    .body(Body::empty())
+                    .expect("request"),
+            )
+            .await
+            .expect("response");
+
+        assert_eq!(response.status(), StatusCode::OK);
+        assert!(
+            response
+                .headers()
+                .get(header::ACCESS_CONTROL_ALLOW_ORIGIN)
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn non_loopback_bind_without_auth_fails_fast() {
+        let options = AppServerOptions {
+            listen: "0.0.0.0:8787".parse().expect("socket addr"),
+            config_path: None,
+            auth_token: None,
+            insecure_no_auth: true,
+            cors_origins: Vec::new(),
+        };
+
+        let err = resolve_auth_token(&options).expect_err("non-loopback unauth should fail");
+        assert!(
+            err.to_string()
+                .contains("refusing unauthenticated app-server bind")
+        );
+    }
+
+    #[tokio::test]
+    async fn stdio_transport_keeps_raw_config_get_for_legacy_clients() {
+        let state = build_state(None, None).expect("state");
+        {
+            let mut cfg = state.config.write().await;
+            cfg.api_key = Some("sk-deepseek-secret".to_string());
+        }
+
+        let response = process_app_request(
+            &state,
+            AppRequest::ConfigGet {
+                key: "api_key".to_string(),
+            },
+            AppTransport::Stdio,
+        )
+        .await;
+
+        assert_eq!(response.data["value"], "sk-deepseek-secret");
+    }
+}
diff --git a/crates/app-server/src/main.rs b/crates/app-server/src/main.rs
index fef6b65d..9627746e 100644
--- a/crates/app-server/src/main.rs
+++ b/crates/app-server/src/main.rs
@@ -17,6 +17,12 @@ struct Cli {
     port: u16,
     #[arg(long)]
     config: Option<PathBuf>,
+    #[arg(long = "auth-token")]
+    auth_token: Option<String>,
+    #[arg(long, default_value_t = false)]
+    insecure_no_auth: bool,
+    #[arg(long = "cors-origin")]
+    cors_origin: Vec<String>,
 }
 
 #[tokio::main]
@@ -28,6 +34,15 @@ async fn main() -> Result<()> {
     run(AppServerOptions {
         listen,
         config_path: cli.config,
+        auth_token: cli.auth_token.or_else(app_server_token_from_env),
+        insecure_no_auth: cli.insecure_no_auth,
+        cors_origins: cli.cors_origin,
     })
     .await
 }
+
+fn app_server_token_from_env() -> Option<String> {
+    std::env::var("CODEWHALE_APP_SERVER_TOKEN")
+        .ok()
+        .or_else(|| std::env::var("DEEPSEEK_APP_SERVER_TOKEN").ok())
+}
diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml
index 87ef1e74..63a8ddb9 100644
--- a/crates/cli/Cargo.toml
+++ b/crates/cli/Cargo.toml
@@ -25,18 +25,20 @@ path = "src/bin/deepseek_legacy_shim.rs"
 anyhow.workspace = true
 clap.workspace = true
 clap_complete.workspace = true
-codewhale-agent = { path = "../agent", version = "0.8.44" }
-codewhale-app-server = { path = "../app-server", version = "0.8.44" }
-codewhale-config = { path = "../config", version = "0.8.44" }
-codewhale-execpolicy = { path = "../execpolicy", version = "0.8.44" }
-codewhale-mcp = { path = "../mcp", version = "0.8.44" }
-codewhale-secrets = { path = "../secrets", version = "0.8.44" }
-codewhale-state = { path = "../state", version = "0.8.44" }
+codewhale-agent = { path = "../agent", version = "0.8.46" }
+codewhale-app-server = { path = "../app-server", version = "0.8.46" }
+codewhale-config = { path = "../config", version = "0.8.46" }
+codewhale-execpolicy = { path = "../execpolicy", version = "0.8.46" }
+codewhale-mcp = { path = "../mcp", version = "0.8.46" }
+codewhale-release = { path = "../release", version = "0.8.46" }
+codewhale-secrets = { path = "../secrets", version = "0.8.46" }
+codewhale-state = { path = "../state", version = "0.8.46" }
 chrono.workspace = true
 dirs.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 reqwest = { workspace = true, features = ["blocking"] }
+semver.workspace = true
 tokio.workspace = true
 sha2.workspace = true
 tempfile = "3.16"
diff --git a/crates/cli/src/bin/codew_legacy_shim.rs b/crates/cli/src/bin/codew_legacy_shim.rs
index 165e05a9..870128fb 100644
--- a/crates/cli/src/bin/codew_legacy_shim.rs
+++ b/crates/cli/src/bin/codew_legacy_shim.rs
@@ -37,12 +37,12 @@ fn spawn_codewhale(args: &[String]) -> std::io::Result<std::process::ExitStatus>
     // same directory as this shim but not on PATH (#2006).
     #[cfg(windows)]
     {
-        if let Ok(exe_path) = env::current_exe() {
-            if let Some(dir) = exe_path.parent() {
-                let sibling = dir.join("codewhale.exe");
-                if sibling.is_file() {
-                    return Command::new(sibling).args(args).status();
-                }
+        if let Ok(exe_path) = env::current_exe()
+            && let Some(dir) = exe_path.parent()
+        {
+            let sibling = dir.join("codewhale.exe");
+            if sibling.is_file() {
+                return Command::new(sibling).args(args).status();
             }
         }
     }
diff --git a/crates/cli/src/bin/deepseek_legacy_shim.rs b/crates/cli/src/bin/deepseek_legacy_shim.rs
index b47c9d92..abd00896 100644
--- a/crates/cli/src/bin/deepseek_legacy_shim.rs
+++ b/crates/cli/src/bin/deepseek_legacy_shim.rs
@@ -44,12 +44,12 @@ fn spawn_codewhale(args: &[String]) -> std::io::Result<std::process::ExitStatus>
     // same directory as this shim but not on PATH (#2006).
     #[cfg(windows)]
     {
-        if let Ok(exe_path) = env::current_exe() {
-            if let Some(dir) = exe_path.parent() {
-                let sibling = dir.join("codewhale.exe");
-                if sibling.is_file() {
-                    return Command::new(sibling).args(args).status();
-                }
+        if let Ok(exe_path) = env::current_exe()
+            && let Some(dir) = exe_path.parent()
+        {
+            let sibling = dir.join("codewhale.exe");
+            if sibling.is_file() {
+                return Command::new(sibling).args(args).status();
             }
         }
     }
diff --git a/crates/cli/src/lib.rs b/crates/cli/src/lib.rs
index c27d699f..cdd7cb4f 100644
--- a/crates/cli/src/lib.rs
+++ b/crates/cli/src/lib.rs
@@ -28,9 +28,12 @@ enum ProviderArg {
     Openai,
     Atlascloud,
     WanjieArk,
+    Volcengine,
     Openrouter,
+    XiaomiMimo,
     Novita,
     Fireworks,
+    Moonshot,
     Sglang,
     Vllm,
     Ollama,
@@ -44,9 +47,12 @@ impl From<ProviderArg> for ProviderKind {
             ProviderArg::Openai => ProviderKind::Openai,
             ProviderArg::Atlascloud => ProviderKind::Atlascloud,
             ProviderArg::WanjieArk => ProviderKind::WanjieArk,
+            ProviderArg::Volcengine => ProviderKind::Volcengine,
             ProviderArg::Openrouter => ProviderKind::Openrouter,
+            ProviderArg::XiaomiMimo => ProviderKind::XiaomiMimo,
             ProviderArg::Novita => ProviderKind::Novita,
             ProviderArg::Fireworks => ProviderKind::Fireworks,
+            ProviderArg::Moonshot => ProviderKind::Moonshot,
             ProviderArg::Sglang => ProviderKind::Sglang,
             ProviderArg::Vllm => ProviderKind::Vllm,
             ProviderArg::Ollama => ProviderKind::Ollama,
@@ -180,7 +186,7 @@ working-tree diff. `export` only writes the current diff.
     Serve(TuiPassthroughArgs),
     /// Generate shell completions for the TUI binary.
     Completions(TuiPassthroughArgs),
-    /// Save a provider API key to the shared user config file.
+    /// Configure provider credentials.
     Login(LoginArgs),
     /// Remove saved authentication state.
     Logout,
@@ -230,7 +236,20 @@ The command prints the completion script to stdout; redirect it to a path your s
     /// Print a usage rollup from the audit log and session store.
     Metrics(MetricsArgs),
     /// Check for and apply updates to the `codewhale` binary.
-    Update,
+    Update(UpdateArgs),
+}
+
+#[derive(Debug, Args)]
+struct UpdateArgs {
+    /// Update to the latest beta release instead of the latest stable release.
+    #[arg(long)]
+    beta: bool,
+    /// Only check the latest release; do not download or replace binaries.
+    #[arg(long)]
+    check: bool,
+    /// Proxy URL to use for update HTTP requests.
+    #[arg(long, value_name = "URL")]
+    proxy: Option<String>,
 }
 
 #[derive(Debug, Args)]
@@ -257,16 +276,10 @@ struct TuiPassthroughArgs {
 
 #[derive(Debug, Args)]
 struct LoginArgs {
-    #[arg(long, value_enum, default_value_t = ProviderArg::Deepseek, hide = true)]
-    provider: ProviderArg,
+    #[arg(long, value_enum, hide = true)]
+    provider: Option<ProviderArg>,
     #[arg(long)]
     api_key: Option<String>,
-    #[arg(long, default_value_t = false, hide = true)]
-    chatgpt: bool,
-    #[arg(long, default_value_t = false, hide = true)]
-    device_code: bool,
-    #[arg(long, hide = true)]
-    token: Option<String>,
 }
 
 #[derive(Debug, Args)]
@@ -382,6 +395,11 @@ enum ThreadCommand {
         thread_id: String,
         name: String,
     },
+    /// Remove the custom name from a thread, restoring the default
+    /// `(unnamed)` rendering in `thread list`.
+    ClearName {
+        thread_id: String,
+    },
 }
 
 #[derive(Debug, Args)]
@@ -426,6 +444,12 @@ struct AppServerArgs {
     port: u16,
     #[arg(long)]
     config: Option<PathBuf>,
+    #[arg(long = "auth-token")]
+    auth_token: Option<String>,
+    #[arg(long, default_value_t = false)]
+    insecure_no_auth: bool,
+    #[arg(long = "cors-origin")]
+    cors_origin: Vec<String>,
     #[arg(long, default_value_t = false)]
     stdio: bool,
 }
@@ -555,7 +579,7 @@ fn run() -> Result<()> {
             Ok(())
         }
         Some(Commands::Metrics(args)) => run_metrics_command(args),
-        Some(Commands::Update) => update::run_update(),
+        Some(Commands::Update(args)) => update::run_update(args.beta, args.check, args.proxy),
         None => {
             let resolved_runtime = resolve_runtime_for_dispatch(&mut store, &runtime_overrides);
             let forwarded = root_tui_passthrough(&cli)?;
@@ -652,38 +676,9 @@ fn run_login_command_with_secrets(
     args: LoginArgs,
     secrets: &Secrets,
 ) -> Result<()> {
-    let provider: ProviderKind = args.provider.into();
+    let provider: ProviderKind = args.provider.unwrap_or(ProviderArg::Deepseek).into();
     store.config.provider = provider;
 
-    if args.chatgpt {
-        let token = match args.token {
-            Some(token) => token,
-            None => read_api_key_from_stdin()?,
-        };
-        store.config.auth_mode = Some("chatgpt".to_string());
-        store.config.chatgpt_access_token = Some(token);
-        store.config.device_code_session = None;
-        store.save()?;
-        println!("logged in using chatgpt token mode ({})", provider.as_str());
-        return Ok(());
-    }
-
-    if args.device_code {
-        let token = match args.token {
-            Some(token) => token,
-            None => read_api_key_from_stdin()?,
-        };
-        store.config.auth_mode = Some("device_code".to_string());
-        store.config.device_code_session = Some(token);
-        store.config.chatgpt_access_token = None;
-        store.save()?;
-        println!(
-            "logged in using device code session mode ({})",
-            provider.as_str()
-        );
-        return Ok(());
-    }
-
     let api_key = match args.api_key {
         Some(v) => v,
         None => read_api_key_from_stdin()?,
@@ -719,8 +714,6 @@ fn run_logout_command_with_secrets(store: &mut ConfigStore, secrets: &Secrets) -
     }
     clear_provider_api_key_from_keyring(secrets, active_provider);
     store.config.auth_mode = None;
-    store.config.chatgpt_access_token = None;
-    store.config.device_code_session = None;
     store.save()?;
     println!("logged out");
     Ok(())
@@ -734,9 +727,12 @@ fn provider_slot(provider: ProviderKind) -> &'static str {
         ProviderKind::Openai => "openai",
         ProviderKind::Atlascloud => "atlascloud",
         ProviderKind::WanjieArk => "wanjie-ark",
+        ProviderKind::Volcengine => "volcengine",
         ProviderKind::Openrouter => "openrouter",
+        ProviderKind::XiaomiMimo => "xiaomi-mimo",
         ProviderKind::Novita => "novita",
         ProviderKind::Fireworks => "fireworks",
+        ProviderKind::Moonshot => "moonshot",
         ProviderKind::Sglang => "sglang",
         ProviderKind::Vllm => "vllm",
         ProviderKind::Ollama => "ollama",
@@ -744,15 +740,18 @@ fn provider_slot(provider: ProviderKind) -> &'static str {
 }
 
 /// Provider order used by the `auth list` and `auth status` outputs.
-const PROVIDER_LIST: [ProviderKind; 11] = [
+const PROVIDER_LIST: [ProviderKind; 14] = [
     ProviderKind::Deepseek,
     ProviderKind::NvidiaNim,
     ProviderKind::Openai,
     ProviderKind::Atlascloud,
     ProviderKind::WanjieArk,
+    ProviderKind::Volcengine,
     ProviderKind::Openrouter,
+    ProviderKind::XiaomiMimo,
     ProviderKind::Novita,
     ProviderKind::Fireworks,
+    ProviderKind::Moonshot,
     ProviderKind::Sglang,
     ProviderKind::Vllm,
     ProviderKind::Ollama,
@@ -804,14 +803,21 @@ fn provider_env_vars(provider: ProviderKind) -> &'static [&'static str] {
     match provider {
         ProviderKind::Deepseek => &["DEEPSEEK_API_KEY"],
         ProviderKind::Openrouter => &["OPENROUTER_API_KEY"],
+        ProviderKind::XiaomiMimo => &["XIAOMI_MIMO_API_KEY", "MIMO_API_KEY"],
         ProviderKind::Novita => &["NOVITA_API_KEY"],
         ProviderKind::NvidiaNim => &["NVIDIA_API_KEY", "NVIDIA_NIM_API_KEY", "DEEPSEEK_API_KEY"],
         ProviderKind::Fireworks => &["FIREWORKS_API_KEY"],
+        ProviderKind::Moonshot => &["MOONSHOT_API_KEY", "KIMI_API_KEY"],
         ProviderKind::Sglang => &["SGLANG_API_KEY"],
         ProviderKind::Vllm => &["VLLM_API_KEY"],
         ProviderKind::Ollama => &["OLLAMA_API_KEY"],
         ProviderKind::Openai => &["OPENAI_API_KEY"],
         ProviderKind::Atlascloud => &["ATLASCLOUD_API_KEY"],
+        ProviderKind::Volcengine => &[
+            "VOLCENGINE_API_KEY",
+            "VOLCENGINE_ARK_API_KEY",
+            "ARK_API_KEY",
+        ],
         ProviderKind::WanjieArk => &[
             "WANJIE_ARK_API_KEY",
             "WANJIE_API_KEY",
@@ -904,6 +910,10 @@ fn auth_status_lines(store: &ConfigStore, secrets: &Secrets) -> Vec<String> {
 
     vec![
         format!("provider: {}", provider.as_str()),
+        format!(
+            "auth mode: {}",
+            store.config.auth_mode.as_deref().unwrap_or("api_key")
+        ),
         format!("active source: {active_label}"),
         "lookup order: config -> secret store -> env".to_string(),
         format!(
@@ -1273,6 +1283,16 @@ fn run_thread_command(command: ThreadCommand) -> Result<()> {
             println!("renamed {thread_id}");
             Ok(())
         }
+        ThreadCommand::ClearName { thread_id } => {
+            let mut thread = state
+                .get_thread(&thread_id)?
+                .with_context(|| format!("thread not found: {thread_id}"))?;
+            thread.name = None;
+            thread.updated_at = chrono::Utc::now().timestamp();
+            state.upsert_thread(&thread)?;
+            println!("cleared name for {thread_id}");
+            Ok(())
+        }
     }
 }
 
@@ -1312,9 +1332,18 @@ fn run_app_server_command(args: AppServerArgs) -> Result<()> {
     runtime.block_on(run_app_server(AppServerOptions {
         listen,
         config_path: args.config,
+        auth_token: args.auth_token.or_else(app_server_token_from_env),
+        insecure_no_auth: args.insecure_no_auth,
+        cors_origins: args.cors_origin,
     }))
 }
 
+fn app_server_token_from_env() -> Option<String> {
+    std::env::var("CODEWHALE_APP_SERVER_TOKEN")
+        .ok()
+        .or_else(|| std::env::var("DEEPSEEK_APP_SERVER_TOKEN").ok())
+}
+
 fn run_mcp_server_command(store: &mut ConfigStore) -> Result<()> {
     let persisted = load_mcp_server_definitions(store);
     let updated = run_stdio_server(persisted)?;
@@ -1464,46 +1493,42 @@ fn build_tui_command(
             | ProviderKind::Atlascloud
             | ProviderKind::WanjieArk
             | ProviderKind::Openrouter
+            | ProviderKind::XiaomiMimo
             | ProviderKind::Novita
             | ProviderKind::Fireworks
+            | ProviderKind::Moonshot
             | ProviderKind::Sglang
             | ProviderKind::Vllm
             | ProviderKind::Ollama
     ) {
         bail!(
-            "The interactive TUI supports DeepSeek, NVIDIA NIM, OpenAI-compatible, AtlasCloud, Wanjie Ark, OpenRouter, Novita, Fireworks, SGLang, vLLM, and Ollama providers. Remove --provider {} or use `codewhale model ...` for provider registry inspection.",
+            "The interactive TUI supports DeepSeek, NVIDIA NIM, OpenAI-compatible, AtlasCloud, Wanjie Ark, OpenRouter, Xiaomi MiMo, Novita, Fireworks, Moonshot/Kimi, SGLang, vLLM, and Ollama providers. Remove --provider {} or use `codewhale model ...` for provider registry inspection.",
             resolved_runtime.provider.as_str()
         );
     }
 
-    cmd.env("DEEPSEEK_MODEL", &resolved_runtime.model);
-    cmd.env("DEEPSEEK_BASE_URL", &resolved_runtime.base_url);
-    cmd.env("DEEPSEEK_PROVIDER", resolved_runtime.provider.as_str());
-    if !resolved_runtime.http_headers.is_empty() {
-        let encoded = resolved_runtime
-            .http_headers
-            .iter()
-            .map(|(name, value)| format!("{}={}", name.trim(), value.trim()))
-            .collect::<Vec<_>>()
-            .join(",");
-        cmd.env("DEEPSEEK_HTTP_HEADERS", encoded);
+    if let Some(provider) = cli.provider {
+        let provider: ProviderKind = provider.into();
+        cmd.env("DEEPSEEK_PROVIDER", provider.as_str());
     }
-    if let Some(api_key) = resolved_runtime.api_key.as_ref() {
+    if matches!(
+        resolved_runtime.api_key_source,
+        Some(RuntimeApiKeySource::Keyring)
+    ) && let Some(api_key) = resolved_runtime.api_key.as_ref()
+    {
+        // TUI reloads auth_mode from config/profile, but it does not re-query the
+        // platform keyring on normal startup. Bridge only the recovered secret;
+        // replaying auth_mode here would turn it back into a profile override.
         cmd.env("DEEPSEEK_API_KEY", api_key);
-        if resolved_runtime.provider == ProviderKind::Openai {
-            cmd.env("OPENAI_API_KEY", api_key);
+        for var in provider_env_vars(resolved_runtime.provider) {
+            if *var != "DEEPSEEK_API_KEY" {
+                cmd.env(var, api_key);
+            }
         }
-        if resolved_runtime.provider == ProviderKind::Atlascloud {
-            cmd.env("ATLASCLOUD_API_KEY", api_key);
-        }
-        if resolved_runtime.provider == ProviderKind::WanjieArk {
-            cmd.env("WANJIE_ARK_API_KEY", api_key);
-        }
-        let source = resolved_runtime
-            .api_key_source
-            .unwrap_or(RuntimeApiKeySource::Env)
-            .as_env_value();
-        cmd.env("DEEPSEEK_API_KEY_SOURCE", source);
+        cmd.env(
+            "DEEPSEEK_API_KEY_SOURCE",
+            RuntimeApiKeySource::Keyring.as_env_value(),
+        );
     }
 
     if let Some(model) = cli.model.as_ref() {
@@ -1538,6 +1563,9 @@ fn build_tui_command(
         if resolved_runtime.provider == ProviderKind::WanjieArk {
             cmd.env("WANJIE_ARK_API_KEY", api_key);
         }
+        if resolved_runtime.provider == ProviderKind::Volcengine {
+            cmd.env("VOLCENGINE_API_KEY", api_key);
+        }
         cmd.env("DEEPSEEK_API_KEY_SOURCE", "cli");
     }
     if let Some(base_url) = cli.base_url.as_ref() {
@@ -1808,6 +1836,47 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn parses_update_beta_flag() {
+        let cli = parse_ok(&["codewhale", "update"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Update(UpdateArgs {
+                beta: false,
+                check: false,
+                proxy: None
+            }))
+        ));
+
+        let cli = parse_ok(&["codewhale", "update", "--beta"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Update(UpdateArgs {
+                beta: true,
+                check: false,
+                proxy: None
+            }))
+        ));
+
+        let cli = parse_ok(&["codewhale", "update", "--check"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Update(UpdateArgs {
+                beta: false,
+                check: true,
+                proxy: None
+            }))
+        ));
+
+        let cli = parse_ok(&["codewhale", "update", "--proxy", "socks5://127.0.0.1:1080"]);
+        let Some(Commands::Update(args)) = cli.command else {
+            panic!("expected update command");
+        };
+        assert!(!args.beta);
+        assert!(!args.check);
+        assert_eq!(args.proxy.as_deref(), Some("socks5://127.0.0.1:1080"));
+    }
+
     #[test]
     fn parses_model_command_matrix() {
         let cli = parse_ok(&["deepseek", "model", "list"]);
@@ -1921,6 +1990,14 @@ mod tests {
                 }
             })) if thread_id == "thread-6" && name == "My Thread"
         ));
+
+        let cli = parse_ok(&["deepseek", "thread", "clear-name", "thread-7"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Thread(ThreadArgs {
+                command: ThreadCommand::ClearName { ref thread_id }
+            })) if thread_id == "thread-7"
+        ));
     }
 
     #[test]
@@ -2035,11 +2112,8 @@ mod tests {
         run_login_command_with_secrets(
             &mut store,
             LoginArgs {
-                provider: ProviderArg::Deepseek,
+                provider: Some(ProviderArg::Deepseek),
                 api_key: Some("sk-test".to_string()),
-                chatgpt: false,
-                device_code: false,
-                token: None,
             },
             &secrets,
         )
@@ -2126,6 +2200,18 @@ mod tests {
             }))
         ));
 
+        let cli = parse_ok(&["deepseek", "auth", "set", "--provider", "moonshot"]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Auth(AuthArgs {
+                command: AuthCommand::Set {
+                    provider: ProviderArg::Moonshot,
+                    api_key: None,
+                    api_key_stdin: false,
+                }
+            }))
+        ));
+
         let cli = parse_ok(&["deepseek", "auth", "set", "--provider", "wanjie-ark"]);
         assert!(matches!(
             cli.command,
@@ -2549,7 +2635,7 @@ mod tests {
             "--profile",
             "work",
             "--model",
-            "gpt-4.1",
+            "deepseek-v4-pro",
             "--output-mode",
             "json",
             "--log-level",
@@ -2561,7 +2647,7 @@ mod tests {
             "--sandbox-mode",
             "workspace-write",
             "--base-url",
-            "https://api.openai.com/v1",
+            "https://openai-compatible.example/v1",
             "--api-key",
             "sk-test",
             "--workspace",
@@ -2571,19 +2657,22 @@ mod tests {
             "--skip-onboarding",
             "model",
             "resolve",
-            "gpt-4.1",
+            "deepseek-v4-pro",
         ]);
 
         assert!(matches!(cli.provider, Some(ProviderArg::Openai)));
         assert_eq!(cli.config, Some(PathBuf::from("/tmp/deepseek.toml")));
         assert_eq!(cli.profile.as_deref(), Some("work"));
-        assert_eq!(cli.model.as_deref(), Some("gpt-4.1"));
+        assert_eq!(cli.model.as_deref(), Some("deepseek-v4-pro"));
         assert_eq!(cli.output_mode.as_deref(), Some("json"));
         assert_eq!(cli.log_level.as_deref(), Some("debug"));
         assert_eq!(cli.telemetry, Some(true));
         assert_eq!(cli.approval_policy.as_deref(), Some("on-request"));
         assert_eq!(cli.sandbox_mode.as_deref(), Some("workspace-write"));
-        assert_eq!(cli.base_url.as_deref(), Some("https://api.openai.com/v1"));
+        assert_eq!(
+            cli.base_url.as_deref(),
+            Some("https://openai-compatible.example/v1")
+        );
         assert_eq!(cli.api_key.as_deref(), Some("sk-test"));
         assert_eq!(cli.workspace, Some(PathBuf::from("/tmp/workspace")));
         assert!(cli.no_alt_screen);
@@ -2631,14 +2720,6 @@ mod tests {
             command_env(&cmd, "DEEPSEEK_PROVIDER").as_deref(),
             Some("openai")
         );
-        assert_eq!(
-            command_env(&cmd, "DEEPSEEK_MODEL").as_deref(),
-            Some("glm-5")
-        );
-        assert_eq!(
-            command_env(&cmd, "DEEPSEEK_BASE_URL").as_deref(),
-            Some("https://openai-compatible.example/v4")
-        );
         assert_eq!(
             command_env(&cmd, "DEEPSEEK_API_KEY").as_deref(),
             Some("resolved-openai-key")
@@ -2651,6 +2732,7 @@ mod tests {
             command_env(&cmd, "DEEPSEEK_API_KEY_SOURCE").as_deref(),
             Some("keyring")
         );
+        assert_eq!(command_env(&cmd, "DEEPSEEK_AUTH_MODE"), None);
         let args: Vec<String> = cmd
             .get_args()
             .map(|arg| arg.to_string_lossy().into_owned())
@@ -2663,11 +2745,283 @@ mod tests {
     }
 
     #[test]
-    fn parses_top_level_prompt_flag_for_canonical_one_shot() {
+    fn build_tui_command_does_not_export_default_runtime_overrides_for_profiles() {
+        let _lock = env_lock();
+        let dir = tempfile::TempDir::new().expect("tempdir");
+        let custom = dir
+            .path()
+            .join(format!("custom-tui{}", std::env::consts::EXE_SUFFIX));
+        std::fs::write(&custom, b"").unwrap();
+        let custom_str = custom.to_string_lossy().into_owned();
+        let _bin = ScopedEnvVar::set("DEEPSEEK_TUI_BIN", &custom_str);
+
+        let cli = parse_ok(&["deepseek", "--profile", "google"]);
+        let mut resolved_headers = std::collections::BTreeMap::new();
+        resolved_headers.insert("X-From-Base".to_string(), "base".to_string());
+        let resolved = ResolvedRuntimeOptions {
+            provider: ProviderKind::Deepseek,
+            model: "deepseek-v4-pro".to_string(),
+            api_key: Some("config-file-key".to_string()),
+            api_key_source: Some(RuntimeApiKeySource::ConfigFile),
+            base_url: "https://api.deepseek.com/beta".to_string(),
+            auth_mode: Some("api_key".to_string()),
+            output_mode: None,
+            log_level: None,
+            telemetry: false,
+            approval_policy: None,
+            sandbox_mode: None,
+            yolo: None,
+            http_headers: resolved_headers,
+        };
+
+        let cmd = build_tui_command(&cli, &resolved, Vec::new()).expect("command");
+
+        assert_eq!(command_env(&cmd, "DEEPSEEK_PROVIDER"), None);
+        assert_eq!(command_env(&cmd, "DEEPSEEK_MODEL"), None);
+        assert_eq!(command_env(&cmd, "DEEPSEEK_BASE_URL"), None);
+        assert_eq!(command_env(&cmd, "DEEPSEEK_API_KEY"), None);
+        assert_eq!(command_env(&cmd, "DEEPSEEK_API_KEY_SOURCE"), None);
+        assert_eq!(command_env(&cmd, "DEEPSEEK_AUTH_MODE"), None);
+        assert_eq!(command_env(&cmd, "DEEPSEEK_HTTP_HEADERS"), None);
+        let args: Vec<String> = cmd
+            .get_args()
+            .map(|arg| arg.to_string_lossy().into_owned())
+            .collect();
+        assert!(
+            args.windows(2).any(|pair| pair == ["--profile", "google"]),
+            "expected profile forwarding in args: {args:?}"
+        );
+    }
+
+    #[test]
+    fn build_tui_command_allows_moonshot_and_forwards_kimi_key() {
+        let _lock = env_lock();
+        let dir = tempfile::TempDir::new().expect("tempdir");
+        let custom = dir
+            .path()
+            .join(format!("custom-tui{}", std::env::consts::EXE_SUFFIX));
+        std::fs::write(&custom, b"").unwrap();
+        let custom_str = custom.to_string_lossy().into_owned();
+        let _bin = ScopedEnvVar::set("DEEPSEEK_TUI_BIN", &custom_str);
+
+        let cli = parse_ok(&[
+            "codewhale",
+            "--provider",
+            "moonshot",
+            "--model",
+            "kimi-k2.6",
+            "--workspace",
+            "/tmp/codewhale-workspace",
+        ]);
+        let resolved = ResolvedRuntimeOptions {
+            provider: ProviderKind::Moonshot,
+            model: "kimi-k2.6".to_string(),
+            api_key: Some("resolved-kimi-key".to_string()),
+            api_key_source: Some(RuntimeApiKeySource::Keyring),
+            base_url: "https://api.moonshot.ai/v1".to_string(),
+            auth_mode: Some("api_key".to_string()),
+            output_mode: None,
+            log_level: None,
+            telemetry: false,
+            approval_policy: None,
+            sandbox_mode: None,
+            yolo: None,
+            http_headers: std::collections::BTreeMap::new(),
+        };
+
+        let cmd = build_tui_command(&cli, &resolved, Vec::new()).expect("command");
+        assert_eq!(
+            command_env(&cmd, "DEEPSEEK_PROVIDER").as_deref(),
+            Some("moonshot")
+        );
+        assert_eq!(
+            command_env(&cmd, "DEEPSEEK_MODEL").as_deref(),
+            Some("kimi-k2.6")
+        );
+        assert_eq!(
+            command_env(&cmd, "DEEPSEEK_API_KEY").as_deref(),
+            Some("resolved-kimi-key")
+        );
+        assert_eq!(
+            command_env(&cmd, "MOONSHOT_API_KEY").as_deref(),
+            Some("resolved-kimi-key")
+        );
+        assert_eq!(
+            command_env(&cmd, "KIMI_API_KEY").as_deref(),
+            Some("resolved-kimi-key")
+        );
+        assert_eq!(
+            command_env(&cmd, "DEEPSEEK_API_KEY_SOURCE").as_deref(),
+            Some("keyring")
+        );
+        assert_eq!(command_env(&cmd, "DEEPSEEK_AUTH_MODE"), None);
+    }
+
+    #[test]
+    fn build_tui_command_exports_explicit_provider_model_and_base_url() {
+        let _lock = env_lock();
+        let dir = tempfile::TempDir::new().expect("tempdir");
+        let custom = dir
+            .path()
+            .join(format!("custom-tui{}", std::env::consts::EXE_SUFFIX));
+        std::fs::write(&custom, b"").unwrap();
+        let custom_str = custom.to_string_lossy().into_owned();
+        let _bin = ScopedEnvVar::set("DEEPSEEK_TUI_BIN", &custom_str);
+
+        let cli = parse_ok(&[
+            "deepseek",
+            "--profile",
+            "google",
+            "--provider",
+            "openai",
+            "--model",
+            "glm-5",
+            "--base-url",
+            "https://openai-compatible.example/v4",
+        ]);
+        let resolved = ResolvedRuntimeOptions {
+            provider: ProviderKind::Openai,
+            model: "glm-5".to_string(),
+            api_key: None,
+            api_key_source: None,
+            base_url: "https://openai-compatible.example/v4".to_string(),
+            auth_mode: None,
+            output_mode: None,
+            log_level: None,
+            telemetry: false,
+            approval_policy: None,
+            sandbox_mode: None,
+            yolo: None,
+            http_headers: std::collections::BTreeMap::new(),
+        };
+
+        let cmd = build_tui_command(&cli, &resolved, Vec::new()).expect("command");
+
+        assert_eq!(
+            command_env(&cmd, "DEEPSEEK_PROVIDER").as_deref(),
+            Some("openai")
+        );
+        assert_eq!(
+            command_env(&cmd, "DEEPSEEK_MODEL").as_deref(),
+            Some("glm-5")
+        );
+        assert_eq!(
+            command_env(&cmd, "DEEPSEEK_BASE_URL").as_deref(),
+            Some("https://openai-compatible.example/v4")
+        );
+    }
+
+    #[test]
+    fn build_tui_command_forwards_provider_keyring_env_vars_for_all_providers() {
+        let _lock = env_lock();
+        let dir = tempfile::TempDir::new().expect("tempdir");
+        let custom = dir
+            .path()
+            .join(format!("custom-tui{}", std::env::consts::EXE_SUFFIX));
+        std::fs::write(&custom, b"").unwrap();
+        let custom_str = custom.to_string_lossy().into_owned();
+        let _bin = ScopedEnvVar::set("DEEPSEEK_TUI_BIN", &custom_str);
+
+        // (provider, cli flag, extra env vars that must be forwarded besides DEEPSEEK_API_KEY)
+        let cases: &[(ProviderKind, &str, &[&str])] = &[
+            (
+                ProviderKind::Openrouter,
+                "openrouter",
+                &["OPENROUTER_API_KEY"],
+            ),
+            (
+                ProviderKind::XiaomiMimo,
+                "xiaomi-mimo",
+                &["XIAOMI_MIMO_API_KEY", "MIMO_API_KEY"],
+            ),
+            (ProviderKind::Novita, "novita", &["NOVITA_API_KEY"]),
+            (
+                ProviderKind::NvidiaNim,
+                "nvidia-nim",
+                &["NVIDIA_API_KEY", "NVIDIA_NIM_API_KEY"],
+            ),
+            (ProviderKind::Fireworks, "fireworks", &["FIREWORKS_API_KEY"]),
+            (ProviderKind::Sglang, "sglang", &["SGLANG_API_KEY"]),
+            (ProviderKind::Vllm, "vllm", &["VLLM_API_KEY"]),
+            (ProviderKind::Ollama, "ollama", &["OLLAMA_API_KEY"]),
+            (
+                ProviderKind::Atlascloud,
+                "atlascloud",
+                &["ATLASCLOUD_API_KEY"],
+            ),
+            (
+                ProviderKind::WanjieArk,
+                "wanjie-ark",
+                &[
+                    "WANJIE_ARK_API_KEY",
+                    "WANJIE_API_KEY",
+                    "WANJIE_MAAS_API_KEY",
+                ],
+            ),
+        ];
+
+        for &(provider, flag, expected_vars) in cases {
+            let cli = parse_ok(&[
+                "codewhale",
+                "--provider",
+                flag,
+                "--workspace",
+                "/tmp/codewhale-workspace",
+            ]);
+            let resolved = ResolvedRuntimeOptions {
+                provider,
+                model: "test-model".to_string(),
+                api_key: Some("test-key".to_string()),
+                api_key_source: Some(RuntimeApiKeySource::Keyring),
+                base_url: "http://localhost:8000/v1".to_string(),
+                auth_mode: Some("api_key".to_string()),
+                output_mode: None,
+                log_level: None,
+                telemetry: false,
+                approval_policy: None,
+                sandbox_mode: None,
+                yolo: None,
+                http_headers: std::collections::BTreeMap::new(),
+            };
+
+            let cmd = build_tui_command(&cli, &resolved, Vec::new())
+                .unwrap_or_else(|e| panic!("{flag}: {e}"));
+
+            assert_eq!(
+                command_env(&cmd, "DEEPSEEK_API_KEY").as_deref(),
+                Some("test-key"),
+                "{flag}: DEEPSEEK_API_KEY not forwarded"
+            );
+            for var in expected_vars {
+                assert_eq!(
+                    command_env(&cmd, var).as_deref(),
+                    Some("test-key"),
+                    "{flag}: {var} not forwarded"
+                );
+            }
+            assert_eq!(
+                command_env(&cmd, "DEEPSEEK_API_KEY_SOURCE").as_deref(),
+                Some("keyring"),
+                "{flag}: expected keyring source bridge"
+            );
+            assert_eq!(
+                command_env(&cmd, "DEEPSEEK_AUTH_MODE"),
+                None,
+                "{flag}: auth mode should come from config/profile, not env handoff"
+            );
+        }
+    }
+
+    #[test]
+    fn parses_top_level_prompt_flag_for_interactive_startup_prompt() {
         let cli = parse_ok(&["deepseek", "-p", "Reply with exactly OK."]);
 
         assert_eq!(cli.prompt_flag.as_deref(), Some("Reply with exactly OK."));
         assert!(cli.prompt.is_empty());
+        assert_eq!(
+            root_tui_passthrough(&cli).unwrap(),
+            vec!["--prompt".to_string(), "Reply with exactly OK.".to_string()]
+        );
     }
 
     #[test]
@@ -2681,7 +3035,7 @@ mod tests {
     }
 
     #[test]
-    fn top_level_continue_rejects_one_shot_prompt() {
+    fn top_level_continue_rejects_startup_prompt() {
         let cli = parse_ok(&["codewhale", "--continue", "-p", "follow up"]);
 
         let err = root_tui_passthrough(&cli).expect_err("prompted continue should be rejected");
@@ -2697,6 +3051,10 @@ mod tests {
 
         assert_eq!(cli.prompt, vec!["hello", "world"]);
         assert!(cli.command.is_none());
+        assert_eq!(
+            root_tui_passthrough(&cli).unwrap(),
+            vec!["--prompt".to_string(), "hello world".to_string()]
+        );
     }
 
     #[test]
@@ -2705,6 +3063,10 @@ mod tests {
 
         assert_eq!(cli.prompt_flag.as_deref(), Some("hello"));
         assert_eq!(cli.prompt, vec!["world"]);
+        assert_eq!(
+            root_tui_passthrough(&cli).unwrap(),
+            vec!["--prompt".to_string(), "hello world".to_string()]
+        );
     }
 
     #[test]
@@ -2776,6 +3138,7 @@ mod tests {
                     "archive",
                     "unarchive",
                     "set-name",
+                    "clear-name",
                 ],
             ),
             ("sandbox", vec!["check"]),
diff --git a/crates/cli/src/update.rs b/crates/cli/src/update.rs
index c9d3e481..ed228e47 100644
--- a/crates/cli/src/update.rs
+++ b/crates/cli/src/update.rs
@@ -5,41 +5,79 @@
 //! platform-correct binary, verifies its SHA256 checksum, and atomically
 //! replaces the currently running binary.
 
+use std::cmp::Ordering;
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 
 use anyhow::{Context, Result, bail};
+use codewhale_release::{
+    CHECKSUM_MANIFEST_ASSET, ReleaseChannel, ReleaseQuery, UPDATE_USER_AGENT,
+    compare_release_versions, is_beta_tag, mirror_asset_url, resolve_release_query,
+    update_is_needed, update_network_fallback_hint,
+};
+use reqwest::Proxy;
 use std::io::Write;
 
-const CHECKSUM_MANIFEST_ASSET: &str = "codewhale-artifacts-sha256.txt";
-const LATEST_RELEASE_URL: &str = "https://api.github.com/repos/Hmbown/CodeWhale/releases/latest";
-const CNB_REPO_URL: &str = "https://cnb.cool/codewhale.net/codewhale";
-const RELEASE_BASE_URL_ENV: &str = "DEEPSEEK_TUI_RELEASE_BASE_URL";
-const LEGACY_RELEASE_BASE_URL_ENV: &str = "DEEPSEEK_RELEASE_BASE_URL";
-const UPDATE_VERSION_ENV: &str = "DEEPSEEK_TUI_VERSION";
-const LEGACY_UPDATE_VERSION_ENV: &str = "DEEPSEEK_VERSION";
-const UPDATE_USER_AGENT: &str = "codewhale-updater";
-
 /// Run the self-update workflow.
-pub fn run_update() -> Result<()> {
+pub fn run_update(beta: bool, check_only: bool, proxy_arg: Option<String>) -> Result<()> {
     let current_exe =
         std::env::current_exe().context("failed to determine current executable path")?;
     let targets = update_targets_for_exe(&current_exe);
+    let channel = ReleaseChannel::from_beta_flag(beta);
+    let current_version = env!("CARGO_PKG_VERSION");
+    let proxy = proxy_arg
+        .as_deref()
+        .map(validate_and_build_proxy)
+        .transpose()?;
 
-    println!("Checking for updates...");
+    println!("Checking for {} updates...", channel.label());
     println!("Current binary: {}", current_exe.display());
+    println!("Current version: v{current_version}");
+
+    if check_only {
+        let latest_tag = latest_release_tag(channel, proxy.as_ref())
+            .with_context(update_network_fallback_hint)?;
+        println!("Latest {} release: {latest_tag}", channel.label());
+        if update_is_needed(channel, current_version, &latest_tag)? {
+            println!("Update available. Run `codewhale update` to install {latest_tag}.");
+        } else {
+            match compare_release_versions(current_version, &latest_tag)? {
+                Ordering::Greater => {
+                    println!("Current build is newer than the latest published release.");
+                }
+                Ordering::Less | Ordering::Equal => {
+                    println!("Already up to date.");
+                }
+            }
+        }
+        return Ok(());
+    }
 
     // Step 1: Fetch latest release metadata
-    let release = fetch_latest_release().with_context(update_network_fallback_hint)?;
+    let fetched =
+        fetch_latest_release(channel, proxy.as_ref()).with_context(update_network_fallback_hint)?;
+    let release = &fetched.release;
     let latest_tag = &release.tag_name;
-    println!("Latest release: {latest_tag}");
+    println!("Latest {} release: {latest_tag}", channel.label());
+
+    if let UpdateReleaseSource::Mirror { base_url } = &fetched.source {
+        if channel == ReleaseChannel::Beta {
+            println!(
+                "Using release mirror {}; --beta does not select GitHub beta releases in mirror mode.",
+                base_url
+            );
+        }
+    } else if !update_is_needed(channel, current_version, latest_tag)? {
+        println!("Already up to date; no download needed.");
+        return Ok(());
+    }
 
     // Step 2: Download the aggregated SHA256 checksum manifest if available
-    let checksum_manifest = match select_checksum_manifest_asset(&release) {
+    let checksum_manifest = match select_checksum_manifest_asset(release) {
         Some(checksum_asset) => {
             println!("Downloading {}...", checksum_asset.name);
-            let checksum_bytes =
-                download_url(&checksum_asset.browser_download_url).with_context(|| {
+            let checksum_bytes = download_url(&checksum_asset.browser_download_url, proxy.as_ref())
+                .with_context(|| {
                     format!(
                         "failed to download {}\n{}",
                         checksum_asset.name,
@@ -59,7 +97,7 @@ pub fn run_update() -> Result<()> {
     // Step 3: Download and verify every colocated binary in the install.
     let mut downloads = Vec::new();
     for target in &targets {
-        let asset = select_platform_asset(&release, &target.asset_stem).with_context(|| {
+        let asset = select_platform_asset(release, &target.asset_stem).with_context(|| {
             format!(
                 "no asset found for platform {} in release {latest_tag}. \
                      Available assets: {}",
@@ -74,13 +112,14 @@ pub fn run_update() -> Result<()> {
         })?;
 
         println!("Downloading {}...", asset.name);
-        let bytes = download_url(&asset.browser_download_url).with_context(|| {
-            format!(
-                "failed to download {}\n{}",
-                asset.name,
-                update_network_fallback_hint()
-            )
-        })?;
+        let bytes =
+            download_url(&asset.browser_download_url, proxy.as_ref()).with_context(|| {
+                format!(
+                    "failed to download {}\n{}",
+                    asset.name,
+                    update_network_fallback_hint()
+                )
+            })?;
 
         if let Some(checksums) = &checksum_manifest {
             let expected = checksums
@@ -122,6 +161,18 @@ pub fn run_update() -> Result<()> {
     Ok(())
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct FetchedRelease {
+    release: Release,
+    source: UpdateReleaseSource,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum UpdateReleaseSource {
+    GitHub,
+    Mirror { base_url: String },
+}
+
 pub(crate) fn release_arch_for_rust_arch(arch: &str) -> &str {
     match arch {
         "aarch64" => "arm64",
@@ -275,54 +326,70 @@ fn expected_sha256_from_manifest(text: &str, asset_name: &str) -> Result<String>
 }
 
 /// GitHub release metadata.
-#[derive(serde::Deserialize, Debug)]
+#[derive(serde::Deserialize, Debug, Clone, PartialEq, Eq)]
 struct Release {
     tag_name: String,
+    #[serde(default)]
+    prerelease: bool,
     assets: Vec<Asset>,
 }
 
 /// A single release asset.
-#[derive(serde::Deserialize, Debug)]
+#[derive(serde::Deserialize, Debug, Clone, PartialEq, Eq)]
 struct Asset {
     name: String,
     browser_download_url: String,
 }
 
-fn update_http_client() -> Result<reqwest::blocking::Client> {
-    reqwest::blocking::Client::builder()
+/// Validate the proxy URL format and build a proxy for update HTTP requests.
+pub(crate) fn validate_and_build_proxy(proxy_str: &str) -> Result<Proxy> {
+    let proxy_url = reqwest::Url::parse(proxy_str).with_context(|| {
+        format!(
+            "invalid proxy URL: {proxy_str}\n\
+             Expected format: http://host:port, https://host:port, or socks5://host:port"
+        )
+    })?;
+    Proxy::all(proxy_url).context("failed to configure update proxy")
+}
+
+fn update_http_client(proxy: Option<&Proxy>) -> Result<reqwest::blocking::Client> {
+    let mut builder = reqwest::blocking::Client::builder();
+    if let Some(proxy) = proxy {
+        builder = builder.proxy(proxy.clone());
+    }
+    builder
         .user_agent(UPDATE_USER_AGENT)
         .build()
         .context("failed to build update HTTP client")
 }
 
-/// Fetch the latest release metadata from GitHub.
-fn fetch_latest_release() -> Result<Release> {
-    if let Some(base_url) = release_base_url_from_env() {
-        let version = update_version_from_env().unwrap_or_else(|| env!("CARGO_PKG_VERSION").into());
-        return Ok(release_from_mirror_base_url(
-            &base_url,
-            &version,
-            std::env::consts::OS,
-            std::env::consts::ARCH,
-        ));
+fn latest_release_tag(channel: ReleaseChannel, proxy: Option<&Proxy>) -> Result<String> {
+    match fetch_latest_release(channel, proxy)? {
+        FetchedRelease { release, .. } => Ok(release.tag_name),
     }
-    fetch_latest_release_from_url(LATEST_RELEASE_URL)
 }
 
-fn release_base_url_from_env() -> Option<String> {
-    std::env::var(RELEASE_BASE_URL_ENV)
-        .ok()
-        .or_else(|| std::env::var(LEGACY_RELEASE_BASE_URL_ENV).ok())
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty())
-}
-
-fn update_version_from_env() -> Option<String> {
-    std::env::var(UPDATE_VERSION_ENV)
-        .ok()
-        .or_else(|| std::env::var(LEGACY_UPDATE_VERSION_ENV).ok())
-        .map(|value| value.trim().trim_start_matches('v').to_string())
-        .filter(|value| !value.is_empty())
+/// Fetch the latest release metadata from GitHub.
+fn fetch_latest_release(channel: ReleaseChannel, proxy: Option<&Proxy>) -> Result<FetchedRelease> {
+    match resolve_release_query(channel) {
+        ReleaseQuery::Mirror { base_url, version } => Ok(FetchedRelease {
+            release: release_from_mirror_base_url(
+                &base_url,
+                &version,
+                std::env::consts::OS,
+                std::env::consts::ARCH,
+            ),
+            source: UpdateReleaseSource::Mirror { base_url },
+        }),
+        ReleaseQuery::GitHubLatest { url } => Ok(FetchedRelease {
+            release: fetch_latest_release_from_url(url, proxy)?,
+            source: UpdateReleaseSource::GitHub,
+        }),
+        ReleaseQuery::GitHubReleaseList { url } => Ok(FetchedRelease {
+            release: fetch_latest_beta_release_from_url(url, proxy)?,
+            source: UpdateReleaseSource::GitHub,
+        }),
+    }
 }
 
 fn release_from_mirror_base_url(
@@ -345,42 +412,32 @@ fn release_from_mirror_base_url(
         });
     }
 
-    Release { tag_name, assets }
+    Release {
+        tag_name,
+        prerelease: false,
+        assets,
+    }
 }
 
-fn mirror_asset_url(base_url: &str, asset_name: &str) -> String {
-    format!("{}/{}", base_url.trim_end_matches('/'), asset_name)
-}
-
-fn update_network_fallback_hint() -> String {
-    format!(
-        "GitHub release downloads may be blocked or slow on this network.\n\
-         For mainland China, use one of these fallback paths:\n\
-           1. Source build from the CNB mirror, installing both shipped binaries:\n\
-              cargo install --git {CNB_REPO_URL} --tag vX.Y.Z codewhale-cli --locked --force\n\
-              cargo install --git {CNB_REPO_URL} --tag vX.Y.Z codewhale-tui --locked --force\n\
-           2. Use a binary asset mirror:\n\
-              {RELEASE_BASE_URL_ENV}=https://<mirror>/<release-assets>/ {UPDATE_VERSION_ENV}=X.Y.Z codewhale update\n\
-         The mirror directory must contain {CHECKSUM_MANIFEST_ASSET} and the platform binaries."
-    )
-}
-
-fn fetch_latest_release_from_url(url: &str) -> Result<Release> {
-    let client = update_http_client()?;
+fn fetch_release_json(url: &str, description: &str, proxy: Option<&Proxy>) -> Result<String> {
+    let client = update_http_client(proxy)?;
     let response = client
         .get(url)
         .header(reqwest::header::ACCEPT, "application/vnd.github+json")
         .send()
-        .with_context(|| format!("failed to fetch release info from {url}"))?;
+        .with_context(|| format!("failed to fetch {description} from {url}"))?;
     let status = response.status();
     let body = response
         .text()
-        .with_context(|| format!("failed to read release response from {url}"))?;
-
+        .with_context(|| format!("failed to read {description} response body from {url}"))?;
     if !status.is_success() {
-        bail!("GitHub release request failed with HTTP {status}: {body}");
+        bail!("failed to fetch {description} from {url}: HTTP {status}\n{body}");
     }
+    Ok(body)
+}
 
+fn fetch_latest_release_from_url(url: &str, proxy: Option<&Proxy>) -> Result<Release> {
+    let body = fetch_release_json(url, "release info", proxy)?;
     let release: Release = serde_json::from_str(&body).with_context(|| {
         format!("failed to parse release JSON from GitHub API. Response: {body}")
     })?;
@@ -388,9 +445,23 @@ fn fetch_latest_release_from_url(url: &str) -> Result<Release> {
     Ok(release)
 }
 
+fn fetch_latest_beta_release_from_url(url: &str, proxy: Option<&Proxy>) -> Result<Release> {
+    let body = fetch_release_json(url, "release list", proxy)?;
+    // GitHub caps this endpoint at 100 releases per page. CodeWhale uses the
+    // first page as the latest-beta search window, matching GitHub's ordering.
+    let releases: Vec<Release> = serde_json::from_str(&body).with_context(|| {
+        format!("failed to parse release list JSON from GitHub API. Response: {body}")
+    })?;
+
+    releases
+        .into_iter()
+        .find(|release| is_beta_tag(&release.tag_name))
+        .context("no beta release found in GitHub releases")
+}
+
 /// Download a URL to bytes.
-fn download_url(url: &str) -> Result<Vec<u8>> {
-    let client = update_http_client()?;
+fn download_url(url: &str, proxy: Option<&Proxy>) -> Result<Vec<u8>> {
+    let client = update_http_client(proxy)?;
     let response = client
         .get(url)
         .send()
@@ -837,13 +908,87 @@ E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855  *codewhale-win
         );
     }
 
+    #[test]
+    fn cnb_release_base_url_includes_tag_directory() {
+        assert_eq!(
+            codewhale_release::cnb_release_base_url("0.8.47"),
+            "https://cnb.cool/Hmbown/CodeWhale/-/releases/v0.8.47"
+        );
+        assert_eq!(
+            codewhale_release::cnb_release_base_url("v0.8.47"),
+            "https://cnb.cool/Hmbown/CodeWhale/-/releases/v0.8.47"
+        );
+    }
+
+    #[test]
+    fn stable_update_is_needed_only_when_latest_is_newer() {
+        assert!(update_is_needed(ReleaseChannel::Stable, "0.8.45", "v0.8.46").unwrap());
+        assert!(update_is_needed(ReleaseChannel::Stable, "0.8.45", "v0.9.0-beta.1").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Stable, "0.8.45", "v0.8.45").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Stable, "0.9.0", "v0.9.0-beta.1").unwrap());
+        assert!(
+            !update_is_needed(ReleaseChannel::Stable, "0.9.0-beta.2", "v0.9.0-beta.1").unwrap()
+        );
+    }
+
+    #[test]
+    fn beta_update_allows_switching_from_same_stable_to_beta() {
+        assert!(update_is_needed(ReleaseChannel::Beta, "1.0.0", "v1.0.0-beta.2").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "1.0.0-beta.2", "v1.0.0-beta.2").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "1.0.0-beta.3", "v1.0.0-beta.2").unwrap());
+        assert!(update_is_needed(ReleaseChannel::Beta, "1.0.0-beta.2", "v1.0.0-beta.3").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "2.0.0", "v1.0.0-beta.3").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "1.0.0-rc.1", "v1.0.0-beta.3").unwrap());
+    }
+
+    #[test]
+    fn parse_release_version_accepts_tags_and_build_suffixes() {
+        assert_eq!(
+            codewhale_release::parse_release_version("v0.9.0-beta.1").unwrap(),
+            semver::Version::parse("0.9.0-beta.1").unwrap()
+        );
+        assert_eq!(
+            codewhale_release::parse_release_version("0.8.45 (abcdef123456)").unwrap(),
+            semver::Version::parse("0.8.45").unwrap()
+        );
+    }
+
+    #[test]
+    fn beta_release_detection_requires_beta_tag() {
+        let rc_prerelease = Release {
+            tag_name: "v0.9.0-rc.1".to_string(),
+            prerelease: true,
+            assets: vec![],
+        };
+        let beta_tag = Release {
+            tag_name: "v0.9.0-beta.1".to_string(),
+            prerelease: false,
+            assets: vec![],
+        };
+        let stable = Release {
+            tag_name: "v0.9.0".to_string(),
+            prerelease: false,
+            assets: vec![],
+        };
+
+        assert!(!is_beta_tag(&rc_prerelease.tag_name));
+        assert!(is_beta_tag(&beta_tag.tag_name));
+        assert!(!is_beta_tag(&stable.tag_name));
+    }
+
     #[test]
     fn update_fallback_hint_points_china_users_to_cnb_and_asset_mirrors() {
         let hint = update_network_fallback_hint();
 
-        assert!(hint.contains(CNB_REPO_URL), "{hint}");
-        assert!(hint.contains(RELEASE_BASE_URL_ENV), "{hint}");
-        assert!(hint.contains(UPDATE_VERSION_ENV), "{hint}");
+        assert!(hint.contains(codewhale_release::CNB_REPO_URL), "{hint}");
+        assert!(
+            hint.contains(codewhale_release::RELEASE_BASE_URL_ENV),
+            "{hint}"
+        );
+        assert!(
+            hint.contains(codewhale_release::UPDATE_VERSION_ENV),
+            "{hint}"
+        );
         assert!(hint.contains("codewhale-cli"), "{hint}");
         assert!(hint.contains("codewhale-tui --locked"), "{hint}");
     }
@@ -877,6 +1022,19 @@ E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855  *codewhale-win
         (format!("http://{addr}/release"), request_rx, handle)
     }
 
+    #[test]
+    fn validate_and_build_proxy_accepts_supported_proxy_urls() {
+        validate_and_build_proxy("http://localhost:7897").expect("http proxy");
+        validate_and_build_proxy("https://proxy.example.com:8080").expect("https proxy");
+        validate_and_build_proxy("socks5://127.0.0.1:1080").expect("socks proxy");
+    }
+
+    #[test]
+    fn validate_and_build_proxy_rejects_malformed_urls() {
+        let err = validate_and_build_proxy("not a valid url").expect_err("malformed URL");
+        assert!(err.to_string().contains("invalid proxy URL"));
+    }
+
     #[test]
     fn fetch_latest_release_from_url_reads_mocked_release_json() {
         let body = br#"{
@@ -887,7 +1045,7 @@ E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855  *codewhale-win
           ]
         }"#;
         let (url, request_rx, handle) = serve_http_once("200 OK", "application/json", body);
-        let release = fetch_latest_release_from_url(&url).expect("release JSON should parse");
+        let release = fetch_latest_release_from_url(&url, None).expect("release JSON should parse");
 
         assert_eq!(release.tag_name, "v9.9.9");
         assert_eq!(release.assets.len(), 2);
@@ -910,7 +1068,7 @@ E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855  *codewhale-win
     fn fetch_latest_release_from_url_reports_http_errors() {
         let (url, _request_rx, handle) =
             serve_http_once("500 Internal Server Error", "text/plain", b"server broke");
-        let err = fetch_latest_release_from_url(&url).expect_err("HTTP 500 should fail");
+        let err = fetch_latest_release_from_url(&url, None).expect_err("HTTP 500 should fail");
 
         assert!(
             err.to_string().contains("HTTP 500"),
@@ -919,11 +1077,54 @@ E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855  *codewhale-win
         handle.join().expect("test server thread");
     }
 
+    #[test]
+    fn fetch_latest_beta_release_from_url_selects_first_beta_release() {
+        let body = br#"[
+          { "tag_name": "v0.9.0", "prerelease": false, "assets": [] },
+          { "tag_name": "v0.9.0-rc.1", "prerelease": true, "assets": [] },
+          { "tag_name": "v0.9.0-beta.2", "prerelease": true, "assets": [
+            { "name": "codewhale-linux-x64", "browser_download_url": "http://example.invalid/codewhale-linux-x64" }
+          ] },
+          { "tag_name": "v0.9.0-beta.1", "prerelease": true, "assets": [] }
+        ]"#;
+        let (url, request_rx, handle) = serve_http_once("200 OK", "application/json", body);
+        let release =
+            fetch_latest_beta_release_from_url(&url, None).expect("beta release JSON should parse");
+
+        assert_eq!(release.tag_name, "v0.9.0-beta.2");
+        assert!(release.prerelease);
+
+        let request = request_rx.recv().expect("captured request");
+        let request_lower = request.to_ascii_lowercase();
+        assert!(request.starts_with("GET /release "), "got {request:?}");
+        assert!(
+            request_lower.contains("accept: application/vnd.github+json"),
+            "got {request:?}"
+        );
+        handle.join().expect("test server thread");
+    }
+
+    #[test]
+    fn fetch_latest_beta_release_from_url_reports_missing_beta() {
+        let body = br#"[
+          { "tag_name": "v0.9.0", "prerelease": false, "assets": [] }
+        ]"#;
+        let (url, _request_rx, handle) = serve_http_once("200 OK", "application/json", body);
+        let err =
+            fetch_latest_beta_release_from_url(&url, None).expect_err("missing beta should fail");
+
+        assert!(
+            err.to_string().contains("no beta release found"),
+            "unexpected error: {err:#}"
+        );
+        handle.join().expect("test server thread");
+    }
+
     #[test]
     fn download_url_reads_binary_body_with_updater_user_agent() {
         let (url, request_rx, handle) =
             serve_http_once("200 OK", "application/octet-stream", b"\0binary bytes");
-        let bytes = download_url(&url).expect("binary download should succeed");
+        let bytes = download_url(&url, None).expect("binary download should succeed");
 
         assert_eq!(bytes, b"\0binary bytes");
 
diff --git a/crates/config/Cargo.toml b/crates/config/Cargo.toml
index 2d9ea522..4fbdb03c 100644
--- a/crates/config/Cargo.toml
+++ b/crates/config/Cargo.toml
@@ -8,8 +8,9 @@ description = "Config schema and precedence model for DeepSeek workspace archite
 
 [dependencies]
 anyhow.workspace = true
-codewhale-secrets = { path = "../secrets", version = "0.8.44" }
+codewhale-secrets = { path = "../secrets", version = "0.8.46" }
 dirs.workspace = true
 serde.workspace = true
+serde_json.workspace = true
 toml.workspace = true
 tracing.workspace = true
diff --git a/crates/config/src/lib.rs b/crates/config/src/lib.rs
index 9bfb089e..ce362691 100644
--- a/crates/config/src/lib.rs
+++ b/crates/config/src/lib.rs
@@ -17,7 +17,7 @@ pub const CONFIG_FILE_NAME: &str = "config.toml";
 const DEFAULT_DEEPSEEK_MODEL: &str = "deepseek-v4-pro";
 const DEFAULT_NVIDIA_NIM_MODEL: &str = "deepseek-ai/deepseek-v4-pro";
 const DEFAULT_NVIDIA_NIM_FLASH_MODEL: &str = "deepseek-ai/deepseek-v4-flash";
-const DEFAULT_OPENAI_MODEL: &str = "gpt-4.1";
+const DEFAULT_OPENAI_MODEL: &str = "deepseek-v4-pro";
 const DEFAULT_DEEPSEEK_BASE_URL: &str = "https://api.deepseek.com/beta";
 const DEFAULT_NVIDIA_NIM_BASE_URL: &str = "https://integrate.api.nvidia.com/v1";
 const DEFAULT_OPENAI_BASE_URL: &str = "https://api.openai.com/v1";
@@ -25,14 +25,22 @@ const DEFAULT_ATLASCLOUD_MODEL: &str = "deepseek-ai/deepseek-v4-flash";
 const DEFAULT_ATLASCLOUD_BASE_URL: &str = "https://api.atlascloud.ai/v1";
 const DEFAULT_WANJIE_ARK_MODEL: &str = "deepseek-reasoner";
 const DEFAULT_WANJIE_ARK_BASE_URL: &str = "https://maas-openapi.wanjiedata.com/api/v1";
+const DEFAULT_VOLCENGINE_MODEL: &str = "DeepSeek-V4-Pro";
+const DEFAULT_VOLCENGINE_BASE_URL: &str = "https://ark.cn-beijing.volces.com/api/coding/v3";
 const DEFAULT_OPENROUTER_MODEL: &str = "deepseek/deepseek-v4-pro";
 const DEFAULT_OPENROUTER_FLASH_MODEL: &str = "deepseek/deepseek-v4-flash";
+const DEFAULT_XIAOMI_MIMO_MODEL: &str = "mimo-v2.5-pro";
 const DEFAULT_NOVITA_MODEL: &str = "deepseek/deepseek-v4-pro";
 const DEFAULT_NOVITA_FLASH_MODEL: &str = "deepseek/deepseek-v4-flash";
 const DEFAULT_FIREWORKS_MODEL: &str = "accounts/fireworks/models/deepseek-v4-pro";
+const DEFAULT_MOONSHOT_MODEL: &str = "kimi-k2.6";
+const DEFAULT_MOONSHOT_BASE_URL: &str = "https://api.moonshot.ai/v1";
+const DEFAULT_KIMI_CODE_MODEL: &str = "kimi-for-coding";
+const DEFAULT_KIMI_CODE_BASE_URL: &str = "https://api.kimi.com/coding/v1";
 const DEFAULT_SGLANG_MODEL: &str = "deepseek-ai/DeepSeek-V4-Pro";
 const DEFAULT_SGLANG_FLASH_MODEL: &str = "deepseek-ai/DeepSeek-V4-Flash";
 const DEFAULT_OPENROUTER_BASE_URL: &str = "https://openrouter.ai/api/v1";
+const DEFAULT_XIAOMI_MIMO_BASE_URL: &str = "https://api.xiaomimimo.com/v1";
 const DEFAULT_NOVITA_BASE_URL: &str = "https://api.novita.ai/v1";
 const DEFAULT_FIREWORKS_BASE_URL: &str = "https://api.fireworks.ai/inference/v1";
 const DEFAULT_SGLANG_BASE_URL: &str = "http://localhost:30000/v1";
@@ -54,6 +62,7 @@ pub enum ProviderKind {
     )]
     Deepseek,
     NvidiaNim,
+    #[serde(alias = "open-ai")]
     Openai,
     Atlascloud,
     #[serde(
@@ -65,9 +74,14 @@ pub enum ProviderKind {
         alias = "wanjie_maas"
     )]
     WanjieArk,
+    #[serde(alias = "volcengine-ark", alias = "volcengine_ark", alias = "ark")]
+    Volcengine,
     Openrouter,
+    #[serde(alias = "mimo", alias = "xiaomi", alias = "xiaomi_mimo")]
+    XiaomiMimo,
     Novita,
     Fireworks,
+    Moonshot,
     Sglang,
     Vllm,
     Ollama,
@@ -82,9 +96,12 @@ impl ProviderKind {
             Self::Openai => "openai",
             Self::Atlascloud => "atlascloud",
             Self::WanjieArk => "wanjie-ark",
+            Self::Volcengine => "volcengine",
             Self::Openrouter => "openrouter",
+            Self::XiaomiMimo => "xiaomi-mimo",
             Self::Novita => "novita",
             Self::Fireworks => "fireworks",
+            Self::Moonshot => "moonshot",
             Self::Sglang => "sglang",
             Self::Vllm => "vllm",
             Self::Ollama => "ollama",
@@ -101,9 +118,15 @@ impl ProviderKind {
             "atlascloud" | "atlas-cloud" | "atlas_cloud" | "atlas" => Some(Self::Atlascloud),
             "wanjie" | "wanjie-ark" | "wanjie_ark" | "ark-wanjie" | "ark_wanjie" | "wanjieark"
             | "wanjie-maas" | "wanjie_maas" | "wanjiemaas" => Some(Self::WanjieArk),
+            "volcengine" | "volcengine-ark" | "volcengine_ark" | "ark" | "volc-ark"
+            | "volcengineark" => Some(Self::Volcengine),
             "openrouter" | "open_router" => Some(Self::Openrouter),
+            "xiaomi-mimo" | "xiaomi_mimo" | "xiaomimimo" | "mimo" | "xiaomi" => {
+                Some(Self::XiaomiMimo)
+            }
             "novita" => Some(Self::Novita),
             "fireworks" | "fireworks-ai" => Some(Self::Fireworks),
+            "moonshot" | "moonshot-ai" | "kimi" | "kimi-k2" => Some(Self::Moonshot),
             "sglang" | "sg-lang" => Some(Self::Sglang),
             "vllm" | "v-llm" => Some(Self::Vllm),
             "ollama" | "ollama-local" => Some(Self::Ollama),
@@ -117,6 +140,7 @@ pub struct ProviderConfigToml {
     pub api_key: Option<String>,
     pub base_url: Option<String>,
     pub model: Option<String>,
+    pub auth_mode: Option<String>,
     #[serde(default)]
     pub http_headers: BTreeMap<String, String>,
 }
@@ -134,12 +158,18 @@ pub struct ProvidersToml {
     #[serde(default)]
     pub wanjie_ark: ProviderConfigToml,
     #[serde(default)]
+    pub volcengine: ProviderConfigToml,
+    #[serde(default)]
     pub openrouter: ProviderConfigToml,
     #[serde(default)]
+    pub xiaomi_mimo: ProviderConfigToml,
+    #[serde(default)]
     pub novita: ProviderConfigToml,
     #[serde(default)]
     pub fireworks: ProviderConfigToml,
     #[serde(default)]
+    pub moonshot: ProviderConfigToml,
+    #[serde(default)]
     pub sglang: ProviderConfigToml,
     #[serde(default)]
     pub vllm: ProviderConfigToml,
@@ -156,9 +186,12 @@ impl ProvidersToml {
             ProviderKind::Openai => &self.openai,
             ProviderKind::Atlascloud => &self.atlascloud,
             ProviderKind::WanjieArk => &self.wanjie_ark,
+            ProviderKind::Volcengine => &self.volcengine,
             ProviderKind::Openrouter => &self.openrouter,
+            ProviderKind::XiaomiMimo => &self.xiaomi_mimo,
             ProviderKind::Novita => &self.novita,
             ProviderKind::Fireworks => &self.fireworks,
+            ProviderKind::Moonshot => &self.moonshot,
             ProviderKind::Sglang => &self.sglang,
             ProviderKind::Vllm => &self.vllm,
             ProviderKind::Ollama => &self.ollama,
@@ -172,9 +205,12 @@ impl ProvidersToml {
             ProviderKind::Openai => &mut self.openai,
             ProviderKind::Atlascloud => &mut self.atlascloud,
             ProviderKind::WanjieArk => &mut self.wanjie_ark,
+            ProviderKind::Volcengine => &mut self.volcengine,
             ProviderKind::Openrouter => &mut self.openrouter,
+            ProviderKind::XiaomiMimo => &mut self.xiaomi_mimo,
             ProviderKind::Novita => &mut self.novita,
             ProviderKind::Fireworks => &mut self.fireworks,
+            ProviderKind::Moonshot => &mut self.moonshot,
             ProviderKind::Sglang => &mut self.sglang,
             ProviderKind::Vllm => &mut self.vllm,
             ProviderKind::Ollama => &mut self.ollama,
@@ -198,13 +234,14 @@ pub struct ConfigToml {
     pub provider: ProviderKind,
     pub model: Option<String>,
     pub auth_mode: Option<String>,
-    pub chatgpt_access_token: Option<String>,
-    pub device_code_session: Option<String>,
     pub output_mode: Option<String>,
     pub log_level: Option<String>,
     pub telemetry: Option<bool>,
     pub approval_policy: Option<String>,
     pub sandbox_mode: Option<String>,
+    /// Native tool catalog controls shared with `codewhale-tui`.
+    #[serde(default)]
+    pub tools: Option<ToolsToml>,
     #[serde(default)]
     pub providers: ProvidersToml,
     /// Per-domain network policy (#135). When absent, network tools fall back
@@ -242,6 +279,14 @@ pub struct SkillsToml {
     pub max_install_size_bytes: Option<u64>,
 }
 
+/// On-disk schema for the `[tools]` table (#2076).
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct ToolsToml {
+    /// Native tool names to keep loaded outside the default core catalog.
+    #[serde(default)]
+    pub always_load: Vec<String>,
+}
+
 /// On-disk schema for the `[snapshots]` table (#137). See
 /// `config.example.toml` for documentation.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -331,91 +376,67 @@ pub struct LspConfigToml {
 }
 
 impl ConfigToml {
-    /// Merge project-level overrides from `$WORKSPACE/.deepseek/config.toml`.
-    /// Only populated fields in `project` are applied; everything else
-    /// keeps its global value. Provider-specific sub-tables are merged
-    /// field-by-field so a project can set just `providers.deepseek.model`
-    /// without needing to repeat `api_key` or `base_url`.
+    /// Merge safe project-level overrides from `$WORKSPACE/.codewhale/config.toml`
+    /// or legacy `$WORKSPACE/.deepseek/config.toml`.
+    ///
+    /// Repo-local config is untrusted input. This helper intentionally ignores
+    /// credentials, endpoints, provider selection, auth/session values, telemetry,
+    /// network policy, skill registry, LSP command tables, and unknown extras.
+    /// Approval and sandbox values may only tighten the existing user/global
+    /// posture.
     pub fn merge_project_overrides(&mut self, project: ConfigToml) {
-        // Check provider override condition before moving fields.
-        let has_api_key = project.api_key.is_some();
-
-        // Top-level scalar fields: apply when the project has a value.
-        if has_api_key {
-            self.api_key = project.api_key;
-        }
-        if project.base_url.is_some() {
-            self.base_url = project.base_url;
-        }
-        if !project.http_headers.is_empty() {
-            self.http_headers = project.http_headers;
-        }
         if project.default_text_model.is_some() {
             self.default_text_model = project.default_text_model;
         }
         if project.model.is_some() {
             self.model = project.model;
         }
-        if project.auth_mode.is_some() {
-            self.auth_mode = project.auth_mode;
-        }
         if project.output_mode.is_some() {
             self.output_mode = project.output_mode;
         }
-        if project.telemetry.is_some() {
-            self.telemetry = project.telemetry;
+        if project.log_level.is_some() {
+            self.log_level = project.log_level;
         }
-        if project.approval_policy.is_some() {
-            self.approval_policy = project.approval_policy;
+        if let Some(policy) = project.approval_policy
+            && project_approval_policy_is_allowed(self.approval_policy.as_deref(), &policy)
+        {
+            self.approval_policy = Some(policy);
         }
-        if project.sandbox_mode.is_some() {
-            self.sandbox_mode = project.sandbox_mode;
+        if let Some(mode) = project.sandbox_mode
+            && project_sandbox_mode_is_allowed(self.sandbox_mode.as_deref(), &mode)
+        {
+            self.sandbox_mode = Some(mode);
         }
-        // Provider is only overridden if explicitly set (non-default).
-        if project.provider != ProviderKind::Deepseek || has_api_key {
-            self.provider = project.provider;
+        if project.tools.is_some() {
+            self.tools = project.tools;
         }
-
-        // Merge provider sub-tables field-by-field.
-        merge_provider_config(&mut self.providers.deepseek, &project.providers.deepseek);
-        merge_provider_config(
+        merge_project_provider_config(&mut self.providers.deepseek, &project.providers.deepseek);
+        merge_project_provider_config(
             &mut self.providers.nvidia_nim,
             &project.providers.nvidia_nim,
         );
-        merge_provider_config(&mut self.providers.openai, &project.providers.openai);
-        merge_provider_config(
+        merge_project_provider_config(&mut self.providers.openai, &project.providers.openai);
+        merge_project_provider_config(
             &mut self.providers.atlascloud,
             &project.providers.atlascloud,
         );
-        merge_provider_config(
+        merge_project_provider_config(
             &mut self.providers.wanjie_ark,
             &project.providers.wanjie_ark,
         );
-        merge_provider_config(
+        merge_project_provider_config(
             &mut self.providers.openrouter,
             &project.providers.openrouter,
         );
-        merge_provider_config(&mut self.providers.novita, &project.providers.novita);
-        merge_provider_config(&mut self.providers.fireworks, &project.providers.fireworks);
-        merge_provider_config(&mut self.providers.sglang, &project.providers.sglang);
-        merge_provider_config(&mut self.providers.vllm, &project.providers.vllm);
-        merge_provider_config(&mut self.providers.ollama, &project.providers.ollama);
-
-        if project.network.is_some() {
-            self.network = project.network;
-        }
-        if project.skills.is_some() {
-            self.skills = project.skills;
-        }
-        if project.snapshots.is_some() {
-            self.snapshots = project.snapshots;
-        }
-        if project.lsp.is_some() {
-            self.lsp = project.lsp;
-        }
-        for (k, v) in project.extras {
-            self.extras.insert(k, v);
-        }
+        merge_project_provider_config(
+            &mut self.providers.xiaomi_mimo,
+            &project.providers.xiaomi_mimo,
+        );
+        merge_project_provider_config(&mut self.providers.novita, &project.providers.novita);
+        merge_project_provider_config(&mut self.providers.fireworks, &project.providers.fireworks);
+        merge_project_provider_config(&mut self.providers.sglang, &project.providers.sglang);
+        merge_project_provider_config(&mut self.providers.vllm, &project.providers.vllm);
+        merge_project_provider_config(&mut self.providers.ollama, &project.providers.ollama);
     }
 
     #[must_use]
@@ -428,13 +449,12 @@ impl ConfigToml {
             "default_text_model" => self.default_text_model.clone(),
             "model" => self.model.clone(),
             "auth.mode" => self.auth_mode.clone(),
-            "auth.chatgpt_access_token" => self.chatgpt_access_token.clone(),
-            "auth.device_code_session" => self.device_code_session.clone(),
             "output_mode" => self.output_mode.clone(),
             "log_level" => self.log_level.clone(),
             "telemetry" => self.telemetry.map(|v| v.to_string()),
             "approval_policy" => self.approval_policy.clone(),
             "sandbox_mode" => self.sandbox_mode.clone(),
+            "tools.always_load" => self.tools.as_ref().map(|tools| tools.always_load.join(",")),
             "providers.deepseek.api_key" => self.providers.deepseek.api_key.clone(),
             "providers.deepseek.base_url" => self.providers.deepseek.base_url.clone(),
             "providers.deepseek.model" => self.providers.deepseek.model.clone(),
@@ -462,6 +482,9 @@ impl ConfigToml {
             "providers.wanjie_ark.api_key" => self.providers.wanjie_ark.api_key.clone(),
             "providers.wanjie_ark.base_url" => self.providers.wanjie_ark.base_url.clone(),
             "providers.wanjie_ark.model" => self.providers.wanjie_ark.model.clone(),
+            "providers.volcengine.api_key" => self.providers.volcengine.api_key.clone(),
+            "providers.volcengine.base_url" => self.providers.volcengine.base_url.clone(),
+            "providers.volcengine.model" => self.providers.volcengine.model.clone(),
             "providers.wanjie_ark.http_headers" => {
                 serialize_http_headers(&self.providers.wanjie_ark.http_headers)
             }
@@ -471,6 +494,12 @@ impl ConfigToml {
             "providers.openrouter.http_headers" => {
                 serialize_http_headers(&self.providers.openrouter.http_headers)
             }
+            "providers.xiaomi_mimo.api_key" => self.providers.xiaomi_mimo.api_key.clone(),
+            "providers.xiaomi_mimo.base_url" => self.providers.xiaomi_mimo.base_url.clone(),
+            "providers.xiaomi_mimo.model" => self.providers.xiaomi_mimo.model.clone(),
+            "providers.xiaomi_mimo.http_headers" => {
+                serialize_http_headers(&self.providers.xiaomi_mimo.http_headers)
+            }
             "providers.novita.api_key" => self.providers.novita.api_key.clone(),
             "providers.novita.base_url" => self.providers.novita.base_url.clone(),
             "providers.novita.model" => self.providers.novita.model.clone(),
@@ -483,6 +512,13 @@ impl ConfigToml {
             "providers.fireworks.http_headers" => {
                 serialize_http_headers(&self.providers.fireworks.http_headers)
             }
+            "providers.moonshot.api_key" => self.providers.moonshot.api_key.clone(),
+            "providers.moonshot.base_url" => self.providers.moonshot.base_url.clone(),
+            "providers.moonshot.model" => self.providers.moonshot.model.clone(),
+            "providers.moonshot.auth_mode" => self.providers.moonshot.auth_mode.clone(),
+            "providers.moonshot.http_headers" => {
+                serialize_http_headers(&self.providers.moonshot.http_headers)
+            }
             "providers.sglang.api_key" => self.providers.sglang.api_key.clone(),
             "providers.sglang.base_url" => self.providers.sglang.base_url.clone(),
             "providers.sglang.model" => self.providers.sglang.model.clone(),
@@ -528,8 +564,6 @@ impl ConfigToml {
             "default_text_model" => self.default_text_model = Some(value.to_string()),
             "model" => self.model = Some(value.to_string()),
             "auth.mode" => self.auth_mode = Some(value.to_string()),
-            "auth.chatgpt_access_token" => self.chatgpt_access_token = Some(value.to_string()),
-            "auth.device_code_session" => self.device_code_session = Some(value.to_string()),
             "output_mode" => self.output_mode = Some(value.to_string()),
             "log_level" => self.log_level = Some(value.to_string()),
             "telemetry" => {
@@ -584,6 +618,15 @@ impl ConfigToml {
             "providers.wanjie_ark.model" => {
                 self.providers.wanjie_ark.model = Some(value.to_string());
             }
+            "providers.volcengine.api_key" => {
+                self.providers.volcengine.api_key = Some(value.to_string());
+            }
+            "providers.volcengine.base_url" => {
+                self.providers.volcengine.base_url = Some(value.to_string());
+            }
+            "providers.volcengine.model" => {
+                self.providers.volcengine.model = Some(value.to_string());
+            }
             "providers.wanjie_ark.http_headers" => {
                 self.providers.wanjie_ark.http_headers = parse_http_headers(value)?;
             }
@@ -611,6 +654,18 @@ impl ConfigToml {
             "providers.openrouter.http_headers" => {
                 self.providers.openrouter.http_headers = parse_http_headers(value)?;
             }
+            "providers.xiaomi_mimo.api_key" => {
+                self.providers.xiaomi_mimo.api_key = Some(value.to_string());
+            }
+            "providers.xiaomi_mimo.base_url" => {
+                self.providers.xiaomi_mimo.base_url = Some(value.to_string());
+            }
+            "providers.xiaomi_mimo.model" => {
+                self.providers.xiaomi_mimo.model = Some(value.to_string());
+            }
+            "providers.xiaomi_mimo.http_headers" => {
+                self.providers.xiaomi_mimo.http_headers = parse_http_headers(value)?;
+            }
             "providers.novita.api_key" => {
                 self.providers.novita.api_key = Some(value.to_string());
             }
@@ -635,6 +690,21 @@ impl ConfigToml {
             "providers.fireworks.http_headers" => {
                 self.providers.fireworks.http_headers = parse_http_headers(value)?;
             }
+            "providers.moonshot.api_key" => {
+                self.providers.moonshot.api_key = Some(value.to_string());
+            }
+            "providers.moonshot.base_url" => {
+                self.providers.moonshot.base_url = Some(value.to_string());
+            }
+            "providers.moonshot.model" => {
+                self.providers.moonshot.model = Some(value.to_string());
+            }
+            "providers.moonshot.auth_mode" => {
+                self.providers.moonshot.auth_mode = Some(value.to_string());
+            }
+            "providers.moonshot.http_headers" => {
+                self.providers.moonshot.http_headers = parse_http_headers(value)?;
+            }
             "providers.sglang.api_key" => {
                 self.providers.sglang.api_key = Some(value.to_string());
             }
@@ -688,8 +758,6 @@ impl ConfigToml {
             "default_text_model" => self.default_text_model = None,
             "model" => self.model = None,
             "auth.mode" => self.auth_mode = None,
-            "auth.chatgpt_access_token" => self.chatgpt_access_token = None,
-            "auth.device_code_session" => self.device_code_session = None,
             "output_mode" => self.output_mode = None,
             "log_level" => self.log_level = None,
             "telemetry" => self.telemetry = None,
@@ -722,6 +790,9 @@ impl ConfigToml {
             "providers.wanjie_ark.api_key" => self.providers.wanjie_ark.api_key = None,
             "providers.wanjie_ark.base_url" => self.providers.wanjie_ark.base_url = None,
             "providers.wanjie_ark.model" => self.providers.wanjie_ark.model = None,
+            "providers.volcengine.api_key" => self.providers.volcengine.api_key = None,
+            "providers.volcengine.base_url" => self.providers.volcengine.base_url = None,
+            "providers.volcengine.model" => self.providers.volcengine.model = None,
             "providers.wanjie_ark.http_headers" => {
                 self.providers.wanjie_ark.http_headers.clear();
             }
@@ -733,6 +804,12 @@ impl ConfigToml {
             "providers.openrouter.base_url" => self.providers.openrouter.base_url = None,
             "providers.openrouter.model" => self.providers.openrouter.model = None,
             "providers.openrouter.http_headers" => self.providers.openrouter.http_headers.clear(),
+            "providers.xiaomi_mimo.api_key" => self.providers.xiaomi_mimo.api_key = None,
+            "providers.xiaomi_mimo.base_url" => self.providers.xiaomi_mimo.base_url = None,
+            "providers.xiaomi_mimo.model" => self.providers.xiaomi_mimo.model = None,
+            "providers.xiaomi_mimo.http_headers" => {
+                self.providers.xiaomi_mimo.http_headers.clear();
+            }
             "providers.novita.api_key" => self.providers.novita.api_key = None,
             "providers.novita.base_url" => self.providers.novita.base_url = None,
             "providers.novita.model" => self.providers.novita.model = None,
@@ -741,6 +818,11 @@ impl ConfigToml {
             "providers.fireworks.base_url" => self.providers.fireworks.base_url = None,
             "providers.fireworks.model" => self.providers.fireworks.model = None,
             "providers.fireworks.http_headers" => self.providers.fireworks.http_headers.clear(),
+            "providers.moonshot.api_key" => self.providers.moonshot.api_key = None,
+            "providers.moonshot.base_url" => self.providers.moonshot.base_url = None,
+            "providers.moonshot.model" => self.providers.moonshot.model = None,
+            "providers.moonshot.auth_mode" => self.providers.moonshot.auth_mode = None,
+            "providers.moonshot.http_headers" => self.providers.moonshot.http_headers.clear(),
             "providers.sglang.api_key" => self.providers.sglang.api_key = None,
             "providers.sglang.base_url" => self.providers.sglang.base_url = None,
             "providers.sglang.model" => self.providers.sglang.model = None,
@@ -783,12 +865,6 @@ impl ConfigToml {
         if let Some(v) = self.auth_mode.as_ref() {
             out.insert("auth.mode".to_string(), v.clone());
         }
-        if let Some(v) = self.chatgpt_access_token.as_ref() {
-            out.insert("auth.chatgpt_access_token".to_string(), redact_secret(v));
-        }
-        if let Some(v) = self.device_code_session.as_ref() {
-            out.insert("auth.device_code_session".to_string(), redact_secret(v));
-        }
         if let Some(v) = self.output_mode.as_ref() {
             out.insert("output_mode".to_string(), v.clone());
         }
@@ -840,6 +916,15 @@ impl ConfigToml {
         if let Some(v) = serialize_http_headers(&self.providers.atlascloud.http_headers) {
             out.insert("providers.atlascloud.http_headers".to_string(), v);
         }
+        if let Some(v) = self.providers.volcengine.api_key.as_ref() {
+            out.insert("providers.volcengine.api_key".to_string(), redact_secret(v));
+        }
+        if let Some(v) = self.providers.volcengine.base_url.as_ref() {
+            out.insert("providers.volcengine.base_url".to_string(), v.clone());
+        }
+        if let Some(v) = self.providers.volcengine.model.as_ref() {
+            out.insert("providers.volcengine.model".to_string(), v.clone());
+        }
         if let Some(v) = self.providers.wanjie_ark.api_key.as_ref() {
             out.insert("providers.wanjie_ark.api_key".to_string(), redact_secret(v));
         }
@@ -849,6 +934,9 @@ impl ConfigToml {
         if let Some(v) = self.providers.wanjie_ark.model.as_ref() {
             out.insert("providers.wanjie_ark.model".to_string(), v.clone());
         }
+        if let Some(v) = serialize_http_headers(&self.providers.volcengine.http_headers) {
+            out.insert("providers.volcengine.http_headers".to_string(), v);
+        }
         if let Some(v) = serialize_http_headers(&self.providers.wanjie_ark.http_headers) {
             out.insert("providers.wanjie_ark.http_headers".to_string(), v);
         }
@@ -876,6 +964,21 @@ impl ConfigToml {
         if let Some(v) = serialize_http_headers(&self.providers.openrouter.http_headers) {
             out.insert("providers.openrouter.http_headers".to_string(), v);
         }
+        if let Some(v) = self.providers.xiaomi_mimo.api_key.as_ref() {
+            out.insert(
+                "providers.xiaomi_mimo.api_key".to_string(),
+                redact_secret(v),
+            );
+        }
+        if let Some(v) = self.providers.xiaomi_mimo.base_url.as_ref() {
+            out.insert("providers.xiaomi_mimo.base_url".to_string(), v.clone());
+        }
+        if let Some(v) = self.providers.xiaomi_mimo.model.as_ref() {
+            out.insert("providers.xiaomi_mimo.model".to_string(), v.clone());
+        }
+        if let Some(v) = serialize_http_headers(&self.providers.xiaomi_mimo.http_headers) {
+            out.insert("providers.xiaomi_mimo.http_headers".to_string(), v);
+        }
         if let Some(v) = self.providers.novita.api_key.as_ref() {
             out.insert("providers.novita.api_key".to_string(), redact_secret(v));
         }
@@ -900,6 +1003,21 @@ impl ConfigToml {
         if let Some(v) = serialize_http_headers(&self.providers.fireworks.http_headers) {
             out.insert("providers.fireworks.http_headers".to_string(), v);
         }
+        if let Some(v) = self.providers.moonshot.api_key.as_ref() {
+            out.insert("providers.moonshot.api_key".to_string(), redact_secret(v));
+        }
+        if let Some(v) = self.providers.moonshot.base_url.as_ref() {
+            out.insert("providers.moonshot.base_url".to_string(), v.clone());
+        }
+        if let Some(v) = self.providers.moonshot.model.as_ref() {
+            out.insert("providers.moonshot.model".to_string(), v.clone());
+        }
+        if let Some(v) = self.providers.moonshot.auth_mode.as_ref() {
+            out.insert("providers.moonshot.auth_mode".to_string(), v.clone());
+        }
+        if let Some(v) = serialize_http_headers(&self.providers.moonshot.http_headers) {
+            out.insert("providers.moonshot.http_headers".to_string(), v);
+        }
         if let Some(v) = self.providers.sglang.api_key.as_ref() {
             out.insert("providers.sglang.api_key".to_string(), redact_secret(v));
         }
@@ -979,6 +1097,12 @@ impl ConfigToml {
         let root_deepseek_model = (provider == ProviderKind::Deepseek)
             .then(|| self.default_text_model.clone())
             .flatten();
+        let auth_mode = cli
+            .auth_mode
+            .clone()
+            .or_else(|| env.auth_mode.clone())
+            .or_else(|| provider_cfg.auth_mode.clone())
+            .or_else(|| self.auth_mode.clone());
         let base_url = cli
             .base_url
             .clone()
@@ -991,26 +1115,34 @@ impl ConfigToml {
                 ProviderKind::Openai => DEFAULT_OPENAI_BASE_URL.to_string(),
                 ProviderKind::Atlascloud => DEFAULT_ATLASCLOUD_BASE_URL.to_string(),
                 ProviderKind::WanjieArk => DEFAULT_WANJIE_ARK_BASE_URL.to_string(),
+                ProviderKind::Volcengine => DEFAULT_VOLCENGINE_BASE_URL.to_string(),
                 ProviderKind::Openrouter => DEFAULT_OPENROUTER_BASE_URL.to_string(),
+                ProviderKind::XiaomiMimo => DEFAULT_XIAOMI_MIMO_BASE_URL.to_string(),
                 ProviderKind::Novita => DEFAULT_NOVITA_BASE_URL.to_string(),
                 ProviderKind::Fireworks => DEFAULT_FIREWORKS_BASE_URL.to_string(),
+                ProviderKind::Moonshot => {
+                    if auth_mode.as_deref().is_some_and(auth_mode_uses_kimi_oauth) {
+                        DEFAULT_KIMI_CODE_BASE_URL.to_string()
+                    } else {
+                        DEFAULT_MOONSHOT_BASE_URL.to_string()
+                    }
+                }
                 ProviderKind::Sglang => DEFAULT_SGLANG_BASE_URL.to_string(),
                 ProviderKind::Vllm => DEFAULT_VLLM_BASE_URL.to_string(),
                 ProviderKind::Ollama => DEFAULT_OLLAMA_BASE_URL.to_string(),
             });
-        let auth_mode = cli
-            .auth_mode
-            .clone()
-            .or_else(|| env.auth_mode.clone())
-            .or_else(|| self.auth_mode.clone());
         // CLI flag wins outright. Otherwise: config-file → injected secrets/env.
         // This makes `deepseek auth set` a reliable fix even when the user's
         // shell still exports an old key. When the file is empty, the injected
         // secrets façade recovers configured secret-store credentials before
         // falling back to ambient env.
+        let uses_kimi_oauth = provider == ProviderKind::Moonshot
+            && auth_mode.as_deref().is_some_and(auth_mode_uses_kimi_oauth);
         let from_file = provider_cfg.api_key.clone().or(root_deepseek_api_key);
         let (api_key, api_key_source) = if let Some(value) = cli.api_key.clone() {
             (Some(value), Some(RuntimeApiKeySource::Cli))
+        } else if uses_kimi_oauth {
+            (None, None)
         } else if let Some(value) = from_file.clone().filter(|v| !v.trim().is_empty()) {
             (Some(value), Some(RuntimeApiKeySource::ConfigFile))
         } else if should_skip_secret_store_for_provider(provider, &base_url, auth_mode.as_deref()) {
@@ -1045,7 +1177,16 @@ impl ConfigToml {
             .or_else(|| provider_cfg.model.clone())
             .or(root_deepseek_model)
             .or_else(|| self.model.clone())
-            .unwrap_or_else(|| default_model_for_provider(provider).to_string());
+            .unwrap_or_else(|| {
+                if provider == ProviderKind::Moonshot
+                    && (auth_mode.as_deref().is_some_and(auth_mode_uses_kimi_oauth)
+                        || moonshot_base_url_uses_kimi_code(&base_url))
+                {
+                    DEFAULT_KIMI_CODE_MODEL.to_string()
+                } else {
+                    default_model_for_provider(provider).to_string()
+                }
+            });
         let model =
             if explicit_model && provider_preserves_custom_base_url_model(provider, &base_url) {
                 model.trim().to_string()
@@ -1105,18 +1246,57 @@ impl ConfigToml {
     }
 }
 
-fn merge_provider_config(target: &mut ProviderConfigToml, source: &ProviderConfigToml) {
-    if source.api_key.is_some() {
-        target.api_key = source.api_key.clone();
-    }
-    if source.base_url.is_some() {
-        target.base_url = source.base_url.clone();
-    }
+fn merge_project_provider_config(target: &mut ProviderConfigToml, source: &ProviderConfigToml) {
     if source.model.is_some() {
         target.model = source.model.clone();
     }
-    if !source.http_headers.is_empty() {
-        target.http_headers = source.http_headers.clone();
+}
+
+#[must_use]
+pub fn project_approval_policy_is_allowed(current: Option<&str>, project: &str) -> bool {
+    let Some(project_rank) = approval_policy_rank(project) else {
+        return false;
+    };
+    match current.and_then(approval_policy_rank) {
+        Some(current_rank) => project_rank >= current_rank,
+        None => project_rank >= 2,
+    }
+}
+
+#[must_use]
+pub fn project_sandbox_mode_is_allowed(current: Option<&str>, project: &str) -> bool {
+    let normalized_project = project.trim().to_ascii_lowercase();
+    if normalized_project == "external-sandbox" {
+        return current
+            .map(|value| value.trim().eq_ignore_ascii_case("external-sandbox"))
+            .unwrap_or(false);
+    }
+
+    let Some(project_rank) = sandbox_mode_rank(project) else {
+        return false;
+    };
+    match current.and_then(sandbox_mode_rank) {
+        Some(current_rank) => project_rank >= current_rank,
+        None => project_rank >= 2,
+    }
+}
+
+fn approval_policy_rank(value: &str) -> Option<u8> {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "auto" => Some(0),
+        "suggest" | "suggested" | "on-request" | "untrusted" => Some(1),
+        "never" | "deny" | "denied" => Some(2),
+        _ => None,
+    }
+}
+
+fn sandbox_mode_rank(value: &str) -> Option<u8> {
+    match value.trim().to_ascii_lowercase().as_str() {
+        "danger-full-access" => Some(0),
+        "external-sandbox" => Some(0),
+        "workspace-write" => Some(1),
+        "read-only" => Some(2),
+        _ => None,
     }
 }
 
@@ -1140,7 +1320,11 @@ pub fn load_project_config(workspace: &Path) -> Option<ConfigToml> {
 fn normalize_model_for_provider(provider: ProviderKind, model: &str) -> String {
     if matches!(
         provider,
-        ProviderKind::Atlascloud | ProviderKind::WanjieArk | ProviderKind::Ollama
+        ProviderKind::Atlascloud
+            | ProviderKind::WanjieArk
+            | ProviderKind::Volcengine
+            | ProviderKind::XiaomiMimo
+            | ProviderKind::Ollama
     ) {
         return model.to_string();
     }
@@ -1174,6 +1358,7 @@ fn normalize_model_for_provider(provider: ProviderKind, model: &str) -> String {
         (ProviderKind::Fireworks, "deepseek-v4-pro" | "deepseek-v4pro") => {
             DEFAULT_FIREWORKS_MODEL.to_string()
         }
+        (ProviderKind::Moonshot, "kimi-k2.6" | "kimi-k2") => DEFAULT_MOONSHOT_MODEL.to_string(),
         (ProviderKind::Sglang, "deepseek-v4-pro" | "deepseek-v4pro") => {
             DEFAULT_SGLANG_MODEL.to_string()
         }
@@ -1201,9 +1386,12 @@ fn default_model_for_provider(provider: ProviderKind) -> &'static str {
         ProviderKind::Openai => DEFAULT_OPENAI_MODEL,
         ProviderKind::Atlascloud => DEFAULT_ATLASCLOUD_MODEL,
         ProviderKind::WanjieArk => DEFAULT_WANJIE_ARK_MODEL,
+        ProviderKind::Volcengine => DEFAULT_VOLCENGINE_MODEL,
         ProviderKind::Openrouter => DEFAULT_OPENROUTER_MODEL,
+        ProviderKind::XiaomiMimo => DEFAULT_XIAOMI_MIMO_MODEL,
         ProviderKind::Novita => DEFAULT_NOVITA_MODEL,
         ProviderKind::Fireworks => DEFAULT_FIREWORKS_MODEL,
+        ProviderKind::Moonshot => DEFAULT_MOONSHOT_MODEL,
         ProviderKind::Sglang => DEFAULT_SGLANG_MODEL,
         ProviderKind::Vllm => DEFAULT_VLLM_MODEL,
         ProviderKind::Ollama => DEFAULT_OLLAMA_MODEL,
@@ -1217,15 +1405,25 @@ fn default_base_url_for_provider(provider: ProviderKind) -> &'static str {
         ProviderKind::Openai => DEFAULT_OPENAI_BASE_URL,
         ProviderKind::Atlascloud => DEFAULT_ATLASCLOUD_BASE_URL,
         ProviderKind::WanjieArk => DEFAULT_WANJIE_ARK_BASE_URL,
+        ProviderKind::Volcengine => DEFAULT_VOLCENGINE_BASE_URL,
         ProviderKind::Openrouter => DEFAULT_OPENROUTER_BASE_URL,
+        ProviderKind::XiaomiMimo => DEFAULT_XIAOMI_MIMO_BASE_URL,
         ProviderKind::Novita => DEFAULT_NOVITA_BASE_URL,
         ProviderKind::Fireworks => DEFAULT_FIREWORKS_BASE_URL,
+        ProviderKind::Moonshot => DEFAULT_MOONSHOT_BASE_URL,
         ProviderKind::Sglang => DEFAULT_SGLANG_BASE_URL,
         ProviderKind::Vllm => DEFAULT_VLLM_BASE_URL,
         ProviderKind::Ollama => DEFAULT_OLLAMA_BASE_URL,
     }
 }
 
+fn moonshot_base_url_uses_kimi_code(base_url: &str) -> bool {
+    let normalized = base_url.trim_end_matches('/').to_ascii_lowercase();
+    normalized == DEFAULT_KIMI_CODE_BASE_URL
+        || normalized == "https://api.kimi.com/coding"
+        || normalized.starts_with("https://api.kimi.com/coding/")
+}
+
 fn base_url_is_custom_for_provider(provider: ProviderKind, base_url: &str) -> bool {
     let actual = base_url.trim_end_matches('/');
     let default = default_base_url_for_provider(provider).trim_end_matches('/');
@@ -1282,6 +1480,17 @@ fn auth_mode_disables_api_key(auth_mode: Option<&str>) -> bool {
     )
 }
 
+fn auth_mode_uses_kimi_oauth(auth_mode: &str) -> bool {
+    matches!(
+        auth_mode
+            .trim()
+            .to_ascii_lowercase()
+            .replace('-', "_")
+            .as_str(),
+        "kimi" | "kimi_oauth" | "kimi_cli" | "oauth"
+    )
+}
+
 fn base_url_uses_local_host(base_url: &str) -> bool {
     let Some(host) = base_url_host(base_url) else {
         return false;
@@ -1512,6 +1721,30 @@ pub fn ensure_state_dir(subdir: &str) -> Result<PathBuf> {
     Ok(dir)
 }
 
+/// Resolve a project-local state subdirectory, preferring `.codewhale/`
+/// when it exists, falling back to `.deepseek/` for legacy projects.
+///
+/// Returns `(true, path)` when the primary `.codewhale/` path is used,
+/// `(false, path)` for the legacy fallback. The boolean helps callers
+/// emit a deprecation notice on legacy paths.
+pub fn resolve_project_state_dir(workspace: &Path, subdir: &str) -> (bool, PathBuf) {
+    let primary = workspace.join(CODEWHALE_APP_DIR).join(subdir);
+    if primary.exists() {
+        return (true, primary);
+    }
+    let legacy = workspace.join(LEGACY_APP_DIR).join(subdir);
+    (false, legacy)
+}
+
+/// Ensure a project-local state subdirectory exists under `.codewhale/`,
+/// creating it if necessary. Returns the directory path.
+pub fn ensure_project_state_dir(workspace: &Path, subdir: &str) -> Result<PathBuf> {
+    let dir = workspace.join(CODEWHALE_APP_DIR).join(subdir);
+    std::fs::create_dir_all(&dir)
+        .with_context(|| format!("failed to create {}/", dir.display()))?;
+    Ok(dir)
+}
+
 pub fn resolve_config_path(explicit: Option<PathBuf>) -> Result<PathBuf> {
     let path = if let Some(path) = explicit {
         path
@@ -1640,10 +1873,7 @@ fn redact_secret(secret: &str) -> String {
 
 #[must_use]
 pub fn is_sensitive_config_key(key: &str) -> bool {
-    matches!(
-        key,
-        "api_key" | "auth.chatgpt_access_token" | "auth.device_code_session"
-    ) || key.ends_with(".api_key")
+    key == "api_key" || key.ends_with(".api_key")
 }
 
 fn normalize_config_file_path(path: PathBuf) -> Result<PathBuf> {
@@ -1671,7 +1901,10 @@ fn normalize_config_file_path(path: PathBuf) -> Result<PathBuf> {
 struct EnvRuntimeOverrides {
     provider: Option<ProviderKind>,
     model: Option<String>,
+    volcengine_model: Option<String>,
     wanjie_ark_model: Option<String>,
+    moonshot_model: Option<String>,
+    xiaomi_mimo_model: Option<String>,
     output_mode: Option<String>,
     auth_mode: Option<String>,
     log_level: Option<String>,
@@ -1684,10 +1917,13 @@ struct EnvRuntimeOverrides {
     nvidia_base_url: Option<String>,
     openai_base_url: Option<String>,
     atlascloud_base_url: Option<String>,
+    volcengine_base_url: Option<String>,
     wanjie_ark_base_url: Option<String>,
     openrouter_base_url: Option<String>,
+    xiaomi_mimo_base_url: Option<String>,
     novita_base_url: Option<String>,
     fireworks_base_url: Option<String>,
+    moonshot_base_url: Option<String>,
     sglang_base_url: Option<String>,
     vllm_base_url: Option<String>,
     ollama_base_url: Option<String>,
@@ -1696,15 +1932,33 @@ struct EnvRuntimeOverrides {
 impl EnvRuntimeOverrides {
     fn load() -> Self {
         Self {
-            provider: std::env::var("DEEPSEEK_PROVIDER")
+            provider: std::env::var("CODEWHALE_PROVIDER")
+                .or_else(|_| std::env::var("DEEPSEEK_PROVIDER"))
                 .ok()
                 .and_then(|v| ProviderKind::parse(&v)),
-            model: std::env::var("DEEPSEEK_MODEL").ok(),
+            model: std::env::var("CODEWHALE_MODEL")
+                .or_else(|_| std::env::var("DEEPSEEK_MODEL"))
+                .or_else(|_| std::env::var("DEEPSEEK_DEFAULT_TEXT_MODEL"))
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
+            volcengine_model: std::env::var("VOLCENGINE_MODEL")
+                .or_else(|_| std::env::var("VOLCENGINE_ARK_MODEL"))
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
             wanjie_ark_model: std::env::var("WANJIE_ARK_MODEL")
                 .or_else(|_| std::env::var("WANJIE_MODEL"))
                 .or_else(|_| std::env::var("WANJIE_MAAS_MODEL"))
                 .ok()
                 .filter(|v| !v.trim().is_empty()),
+            moonshot_model: std::env::var("MOONSHOT_MODEL")
+                .or_else(|_| std::env::var("KIMI_MODEL_NAME"))
+                .or_else(|_| std::env::var("KIMI_MODEL"))
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
+            xiaomi_mimo_model: std::env::var("XIAOMI_MIMO_MODEL")
+                .or_else(|_| std::env::var("MIMO_MODEL"))
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
             output_mode: std::env::var("DEEPSEEK_OUTPUT_MODE").ok(),
             auth_mode: std::env::var("DEEPSEEK_AUTH_MODE").ok(),
             log_level: std::env::var("DEEPSEEK_LOG_LEVEL").ok(),
@@ -1720,7 +1974,8 @@ impl EnvRuntimeOverrides {
                 .ok()
                 .and_then(|value| parse_http_headers(&value).ok())
                 .filter(|headers| !headers.is_empty()),
-            deepseek_base_url: std::env::var("DEEPSEEK_BASE_URL")
+            deepseek_base_url: std::env::var("CODEWHALE_BASE_URL")
+                .or_else(|_| std::env::var("DEEPSEEK_BASE_URL"))
                 .ok()
                 .filter(|v| !v.trim().is_empty()),
             nvidia_base_url: std::env::var("NVIDIA_NIM_BASE_URL")
@@ -1734,6 +1989,11 @@ impl EnvRuntimeOverrides {
             atlascloud_base_url: std::env::var("ATLASCLOUD_BASE_URL")
                 .ok()
                 .filter(|v| !v.trim().is_empty()),
+            volcengine_base_url: std::env::var("VOLCENGINE_BASE_URL")
+                .or_else(|_| std::env::var("VOLCENGINE_ARK_BASE_URL"))
+                .or_else(|_| std::env::var("ARK_BASE_URL"))
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
             wanjie_ark_base_url: std::env::var("WANJIE_ARK_BASE_URL")
                 .or_else(|_| std::env::var("WANJIE_BASE_URL"))
                 .or_else(|_| std::env::var("WANJIE_MAAS_BASE_URL"))
@@ -1742,12 +2002,20 @@ impl EnvRuntimeOverrides {
             openrouter_base_url: std::env::var("OPENROUTER_BASE_URL")
                 .ok()
                 .filter(|v| !v.trim().is_empty()),
+            xiaomi_mimo_base_url: std::env::var("XIAOMI_MIMO_BASE_URL")
+                .or_else(|_| std::env::var("MIMO_BASE_URL"))
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
             novita_base_url: std::env::var("NOVITA_BASE_URL")
                 .ok()
                 .filter(|v| !v.trim().is_empty()),
             fireworks_base_url: std::env::var("FIREWORKS_BASE_URL")
                 .ok()
                 .filter(|v| !v.trim().is_empty()),
+            moonshot_base_url: std::env::var("MOONSHOT_BASE_URL")
+                .or_else(|_| std::env::var("KIMI_BASE_URL"))
+                .ok()
+                .filter(|v| !v.trim().is_empty()),
             sglang_base_url: std::env::var("SGLANG_BASE_URL")
                 .ok()
                 .filter(|v| !v.trim().is_empty()),
@@ -1769,9 +2037,12 @@ impl EnvRuntimeOverrides {
             ProviderKind::Openai => self.openai_base_url.clone(),
             ProviderKind::Atlascloud => self.atlascloud_base_url.clone(),
             ProviderKind::WanjieArk => self.wanjie_ark_base_url.clone(),
+            ProviderKind::Volcengine => self.volcengine_base_url.clone(),
             ProviderKind::Openrouter => self.openrouter_base_url.clone(),
+            ProviderKind::XiaomiMimo => self.xiaomi_mimo_base_url.clone(),
             ProviderKind::Novita => self.novita_base_url.clone(),
             ProviderKind::Fireworks => self.fireworks_base_url.clone(),
+            ProviderKind::Moonshot => self.moonshot_base_url.clone(),
             ProviderKind::Sglang => self.sglang_base_url.clone(),
             ProviderKind::Vllm => self.vllm_base_url.clone(),
             ProviderKind::Ollama => self.ollama_base_url.clone(),
@@ -1781,6 +2052,9 @@ impl EnvRuntimeOverrides {
     fn model_for(&self, provider: ProviderKind) -> Option<String> {
         match provider {
             ProviderKind::WanjieArk => self.wanjie_ark_model.clone(),
+            ProviderKind::Volcengine => self.volcengine_model.clone(),
+            ProviderKind::Moonshot => self.moonshot_model.clone(),
+            ProviderKind::XiaomiMimo => self.xiaomi_mimo_model.clone(),
             _ => None,
         }
     }
@@ -1819,6 +2093,7 @@ mod tests {
         deepseek_base_url: Option<OsString>,
         deepseek_http_headers: Option<OsString>,
         deepseek_model: Option<OsString>,
+        deepseek_default_text_model: Option<OsString>,
         deepseek_provider: Option<OsString>,
         deepseek_auth_mode: Option<OsString>,
         nvidia_api_key: Option<OsString>,
@@ -1828,10 +2103,17 @@ mod tests {
         nvidia_nim_base_url: Option<OsString>,
         openrouter_api_key: Option<OsString>,
         openrouter_base_url: Option<OsString>,
+        xiaomi_mimo_api_key: Option<OsString>,
+        mimo_api_key: Option<OsString>,
+        xiaomi_mimo_base_url: Option<OsString>,
+        mimo_base_url: Option<OsString>,
+        xiaomi_mimo_model: Option<OsString>,
+        mimo_model: Option<OsString>,
         wanjie_ark_api_key: Option<OsString>,
         wanjie_ark_base_url: Option<OsString>,
         wanjie_base_url: Option<OsString>,
         wanjie_maas_base_url: Option<OsString>,
+        volcengine_model: Option<OsString>,
         wanjie_ark_model: Option<OsString>,
         wanjie_model: Option<OsString>,
         wanjie_maas_model: Option<OsString>,
@@ -1839,12 +2121,22 @@ mod tests {
         novita_base_url: Option<OsString>,
         fireworks_api_key: Option<OsString>,
         fireworks_base_url: Option<OsString>,
+        moonshot_api_key: Option<OsString>,
+        moonshot_base_url: Option<OsString>,
+        moonshot_model: Option<OsString>,
+        kimi_api_key: Option<OsString>,
+        kimi_base_url: Option<OsString>,
+        kimi_model: Option<OsString>,
+        kimi_model_name: Option<OsString>,
         sglang_api_key: Option<OsString>,
         sglang_base_url: Option<OsString>,
         vllm_api_key: Option<OsString>,
         vllm_base_url: Option<OsString>,
         ollama_api_key: Option<OsString>,
         ollama_base_url: Option<OsString>,
+        codewhale_provider: Option<OsString>,
+        codewhale_model: Option<OsString>,
+        codewhale_base_url: Option<OsString>,
     }
 
     impl EnvGuard {
@@ -1854,8 +2146,12 @@ mod tests {
                 deepseek_base_url: env::var_os("DEEPSEEK_BASE_URL"),
                 deepseek_http_headers: env::var_os("DEEPSEEK_HTTP_HEADERS"),
                 deepseek_model: env::var_os("DEEPSEEK_MODEL"),
+                deepseek_default_text_model: env::var_os("DEEPSEEK_DEFAULT_TEXT_MODEL"),
                 deepseek_provider: env::var_os("DEEPSEEK_PROVIDER"),
                 deepseek_auth_mode: env::var_os("DEEPSEEK_AUTH_MODE"),
+                codewhale_provider: env::var_os("CODEWHALE_PROVIDER"),
+                codewhale_model: env::var_os("CODEWHALE_MODEL"),
+                codewhale_base_url: env::var_os("CODEWHALE_BASE_URL"),
                 nvidia_api_key: env::var_os("NVIDIA_API_KEY"),
                 nvidia_nim_api_key: env::var_os("NVIDIA_NIM_API_KEY"),
                 nim_base_url: env::var_os("NIM_BASE_URL"),
@@ -1863,10 +2159,17 @@ mod tests {
                 nvidia_nim_base_url: env::var_os("NVIDIA_NIM_BASE_URL"),
                 openrouter_api_key: env::var_os("OPENROUTER_API_KEY"),
                 openrouter_base_url: env::var_os("OPENROUTER_BASE_URL"),
+                xiaomi_mimo_api_key: env::var_os("XIAOMI_MIMO_API_KEY"),
+                mimo_api_key: env::var_os("MIMO_API_KEY"),
+                xiaomi_mimo_base_url: env::var_os("XIAOMI_MIMO_BASE_URL"),
+                mimo_base_url: env::var_os("MIMO_BASE_URL"),
+                xiaomi_mimo_model: env::var_os("XIAOMI_MIMO_MODEL"),
+                mimo_model: env::var_os("MIMO_MODEL"),
                 wanjie_ark_api_key: env::var_os("WANJIE_ARK_API_KEY"),
                 wanjie_ark_base_url: env::var_os("WANJIE_ARK_BASE_URL"),
                 wanjie_base_url: env::var_os("WANJIE_BASE_URL"),
                 wanjie_maas_base_url: env::var_os("WANJIE_MAAS_BASE_URL"),
+                volcengine_model: env::var_os("VOLCENGINE_MODEL"),
                 wanjie_ark_model: env::var_os("WANJIE_ARK_MODEL"),
                 wanjie_model: env::var_os("WANJIE_MODEL"),
                 wanjie_maas_model: env::var_os("WANJIE_MAAS_MODEL"),
@@ -1874,6 +2177,13 @@ mod tests {
                 novita_base_url: env::var_os("NOVITA_BASE_URL"),
                 fireworks_api_key: env::var_os("FIREWORKS_API_KEY"),
                 fireworks_base_url: env::var_os("FIREWORKS_BASE_URL"),
+                moonshot_api_key: env::var_os("MOONSHOT_API_KEY"),
+                moonshot_base_url: env::var_os("MOONSHOT_BASE_URL"),
+                moonshot_model: env::var_os("MOONSHOT_MODEL"),
+                kimi_api_key: env::var_os("KIMI_API_KEY"),
+                kimi_base_url: env::var_os("KIMI_BASE_URL"),
+                kimi_model: env::var_os("KIMI_MODEL"),
+                kimi_model_name: env::var_os("KIMI_MODEL_NAME"),
                 sglang_api_key: env::var_os("SGLANG_API_KEY"),
                 sglang_base_url: env::var_os("SGLANG_BASE_URL"),
                 vllm_api_key: env::var_os("VLLM_API_KEY"),
@@ -1887,8 +2197,12 @@ mod tests {
                 env::remove_var("DEEPSEEK_BASE_URL");
                 env::remove_var("DEEPSEEK_HTTP_HEADERS");
                 env::remove_var("DEEPSEEK_MODEL");
+                env::remove_var("DEEPSEEK_DEFAULT_TEXT_MODEL");
                 env::remove_var("DEEPSEEK_PROVIDER");
                 env::remove_var("DEEPSEEK_AUTH_MODE");
+                env::remove_var("CODEWHALE_PROVIDER");
+                env::remove_var("CODEWHALE_MODEL");
+                env::remove_var("CODEWHALE_BASE_URL");
                 env::remove_var("NVIDIA_API_KEY");
                 env::remove_var("NVIDIA_NIM_API_KEY");
                 env::remove_var("NIM_BASE_URL");
@@ -1896,6 +2210,12 @@ mod tests {
                 env::remove_var("NVIDIA_NIM_BASE_URL");
                 env::remove_var("OPENROUTER_API_KEY");
                 env::remove_var("OPENROUTER_BASE_URL");
+                env::remove_var("XIAOMI_MIMO_API_KEY");
+                env::remove_var("MIMO_API_KEY");
+                env::remove_var("XIAOMI_MIMO_BASE_URL");
+                env::remove_var("MIMO_BASE_URL");
+                env::remove_var("XIAOMI_MIMO_MODEL");
+                env::remove_var("MIMO_MODEL");
                 env::remove_var("WANJIE_ARK_API_KEY");
                 env::remove_var("WANJIE_ARK_BASE_URL");
                 env::remove_var("WANJIE_BASE_URL");
@@ -1907,6 +2227,13 @@ mod tests {
                 env::remove_var("NOVITA_BASE_URL");
                 env::remove_var("FIREWORKS_API_KEY");
                 env::remove_var("FIREWORKS_BASE_URL");
+                env::remove_var("MOONSHOT_API_KEY");
+                env::remove_var("MOONSHOT_BASE_URL");
+                env::remove_var("MOONSHOT_MODEL");
+                env::remove_var("KIMI_API_KEY");
+                env::remove_var("KIMI_BASE_URL");
+                env::remove_var("KIMI_MODEL");
+                env::remove_var("KIMI_MODEL_NAME");
                 env::remove_var("SGLANG_API_KEY");
                 env::remove_var("SGLANG_BASE_URL");
                 env::remove_var("VLLM_API_KEY");
@@ -1934,8 +2261,15 @@ mod tests {
                 Self::restore_var("DEEPSEEK_BASE_URL", self.deepseek_base_url.take());
                 Self::restore_var("DEEPSEEK_HTTP_HEADERS", self.deepseek_http_headers.take());
                 Self::restore_var("DEEPSEEK_MODEL", self.deepseek_model.take());
+                Self::restore_var(
+                    "DEEPSEEK_DEFAULT_TEXT_MODEL",
+                    self.deepseek_default_text_model.take(),
+                );
                 Self::restore_var("DEEPSEEK_PROVIDER", self.deepseek_provider.take());
                 Self::restore_var("DEEPSEEK_AUTH_MODE", self.deepseek_auth_mode.take());
+                Self::restore_var("CODEWHALE_PROVIDER", self.codewhale_provider.take());
+                Self::restore_var("CODEWHALE_MODEL", self.codewhale_model.take());
+                Self::restore_var("CODEWHALE_BASE_URL", self.codewhale_base_url.take());
                 Self::restore_var("NVIDIA_API_KEY", self.nvidia_api_key.take());
                 Self::restore_var("NVIDIA_NIM_API_KEY", self.nvidia_nim_api_key.take());
                 Self::restore_var("NIM_BASE_URL", self.nim_base_url.take());
@@ -1943,10 +2277,17 @@ mod tests {
                 Self::restore_var("NVIDIA_NIM_BASE_URL", self.nvidia_nim_base_url.take());
                 Self::restore_var("OPENROUTER_API_KEY", self.openrouter_api_key.take());
                 Self::restore_var("OPENROUTER_BASE_URL", self.openrouter_base_url.take());
+                Self::restore_var("XIAOMI_MIMO_API_KEY", self.xiaomi_mimo_api_key.take());
+                Self::restore_var("MIMO_API_KEY", self.mimo_api_key.take());
+                Self::restore_var("XIAOMI_MIMO_BASE_URL", self.xiaomi_mimo_base_url.take());
+                Self::restore_var("MIMO_BASE_URL", self.mimo_base_url.take());
+                Self::restore_var("XIAOMI_MIMO_MODEL", self.xiaomi_mimo_model.take());
+                Self::restore_var("MIMO_MODEL", self.mimo_model.take());
                 Self::restore_var("WANJIE_ARK_API_KEY", self.wanjie_ark_api_key.take());
                 Self::restore_var("WANJIE_ARK_BASE_URL", self.wanjie_ark_base_url.take());
                 Self::restore_var("WANJIE_BASE_URL", self.wanjie_base_url.take());
                 Self::restore_var("WANJIE_MAAS_BASE_URL", self.wanjie_maas_base_url.take());
+                Self::restore_var("VOLCENGINE_MODEL", self.volcengine_model.take());
                 Self::restore_var("WANJIE_ARK_MODEL", self.wanjie_ark_model.take());
                 Self::restore_var("WANJIE_MODEL", self.wanjie_model.take());
                 Self::restore_var("WANJIE_MAAS_MODEL", self.wanjie_maas_model.take());
@@ -1954,6 +2295,13 @@ mod tests {
                 Self::restore_var("NOVITA_BASE_URL", self.novita_base_url.take());
                 Self::restore_var("FIREWORKS_API_KEY", self.fireworks_api_key.take());
                 Self::restore_var("FIREWORKS_BASE_URL", self.fireworks_base_url.take());
+                Self::restore_var("MOONSHOT_API_KEY", self.moonshot_api_key.take());
+                Self::restore_var("MOONSHOT_BASE_URL", self.moonshot_base_url.take());
+                Self::restore_var("MOONSHOT_MODEL", self.moonshot_model.take());
+                Self::restore_var("KIMI_API_KEY", self.kimi_api_key.take());
+                Self::restore_var("KIMI_BASE_URL", self.kimi_base_url.take());
+                Self::restore_var("KIMI_MODEL", self.kimi_model.take());
+                Self::restore_var("KIMI_MODEL_NAME", self.kimi_model_name.take());
                 Self::restore_var("SGLANG_API_KEY", self.sglang_api_key.take());
                 Self::restore_var("SGLANG_BASE_URL", self.sglang_base_url.take());
                 Self::restore_var("VLLM_API_KEY", self.vllm_api_key.take());
@@ -2257,7 +2605,6 @@ mod tests {
     fn get_display_value_redacts_sensitive_keys() {
         let mut config = ConfigToml {
             api_key: Some("sk-deepseek-secret".to_string()),
-            chatgpt_access_token: Some("chatgpt-access-secret".to_string()),
             ..ConfigToml::default()
         };
         config.providers.openrouter.api_key = Some("openrouter-secret-value".to_string());
@@ -2267,12 +2614,6 @@ mod tests {
             config.get_display_value("api_key").as_deref(),
             Some("sk-d***cret")
         );
-        assert_eq!(
-            config
-                .get_display_value("auth.chatgpt_access_token")
-                .as_deref(),
-            Some("chat***cret")
-        );
         assert_eq!(
             config
                 .get_display_value("providers.openrouter.api_key")
@@ -2285,6 +2626,182 @@ mod tests {
         );
     }
 
+    /// End-to-end smoke for the preferred Kimi Code setup path:
+    ///   1. Start from a fresh root config that uses DeepSeek defaults.
+    ///   2. Mutate it through the same key-value setters the
+    ///      `codewhale config set providers.moonshot.*` CLI invokes.
+    ///   3. Switch the active provider through `CODEWHALE_PROVIDER` —
+    ///      the public env alias — without ever touching the legacy
+    ///      `DEEPSEEK_PROVIDER` name.
+    ///   4. Resolve the runtime and confirm the doctor/runtime values.
+    ///
+    /// No real API key is required; the `api_key` here is just a
+    /// non-empty placeholder.
+    #[test]
+    fn moonshot_kimi_code_smoke_config_set_then_resolve() -> Result<()> {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+
+        let mut config = ConfigToml {
+            provider: ProviderKind::Deepseek,
+            default_text_model: Some("deepseek-v4-pro".to_string()),
+            ..ConfigToml::default()
+        };
+
+        // Same key paths a user would run via `codewhale config set`.
+        config.set_value("providers.moonshot.api_key", "kimi-code-key-placeholder")?;
+        config.set_value("providers.moonshot.auth_mode", "api_key")?;
+        config.set_value("providers.moonshot.base_url", DEFAULT_KIMI_CODE_BASE_URL)?;
+        config.set_value("providers.moonshot.model", DEFAULT_KIMI_CODE_MODEL)?;
+
+        // Public env alias for the active-provider switch.
+        // Safety: test-only env mutation guarded by env_lock().
+        unsafe { env::set_var("CODEWHALE_PROVIDER", "moonshot") };
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.base_url, DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(resolved.model, DEFAULT_KIMI_CODE_MODEL);
+        assert_eq!(resolved.auth_mode.as_deref(), Some("api_key"));
+        assert_eq!(
+            resolved.api_key.as_deref(),
+            Some("kimi-code-key-placeholder")
+        );
+        assert_eq!(
+            resolved.api_key_source,
+            Some(RuntimeApiKeySource::ConfigFile)
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn moonshot_provider_config_values_round_trip() -> Result<()> {
+        let mut config = ConfigToml::default();
+
+        config.set_value("providers.moonshot.api_key", "moonshot-secret-value")?;
+        config.set_value("providers.moonshot.base_url", DEFAULT_KIMI_CODE_BASE_URL)?;
+        config.set_value("providers.moonshot.model", DEFAULT_KIMI_CODE_MODEL)?;
+        config.set_value("providers.moonshot.auth_mode", "api_key")?;
+        config.set_value("providers.moonshot.http_headers", "X-Test=ok")?;
+
+        assert_eq!(
+            config
+                .get_display_value("providers.moonshot.api_key")
+                .as_deref(),
+            Some("moon***alue")
+        );
+        assert_eq!(
+            config.get_value("providers.moonshot.base_url").as_deref(),
+            Some(DEFAULT_KIMI_CODE_BASE_URL)
+        );
+        assert_eq!(
+            config.get_value("providers.moonshot.model").as_deref(),
+            Some(DEFAULT_KIMI_CODE_MODEL)
+        );
+        assert_eq!(
+            config.get_value("providers.moonshot.auth_mode").as_deref(),
+            Some("api_key")
+        );
+        assert_eq!(
+            config
+                .list_values()
+                .get("providers.moonshot.api_key")
+                .map(String::as_str),
+            Some("moon***alue")
+        );
+
+        config.unset_value("providers.moonshot.auth_mode")?;
+        config.unset_value("providers.moonshot.base_url")?;
+        config.unset_value("providers.moonshot.model")?;
+
+        assert_eq!(config.get_value("providers.moonshot.auth_mode"), None);
+        assert_eq!(config.get_value("providers.moonshot.base_url"), None);
+        assert_eq!(config.get_value("providers.moonshot.model"), None);
+        Ok(())
+    }
+
+    #[test]
+    fn project_merge_denies_credentials_endpoints_and_provider_selection() {
+        let mut base = ConfigToml {
+            provider: ProviderKind::Deepseek,
+            api_key: Some("user-key".to_string()),
+            base_url: Some("https://api.deepseek.com".to_string()),
+            default_text_model: Some("deepseek-v4-flash".to_string()),
+            ..ConfigToml::default()
+        };
+        base.providers.openrouter.api_key = Some("user-openrouter-key".to_string());
+
+        let mut project = ConfigToml {
+            provider: ProviderKind::Openrouter,
+            api_key: Some("attacker-key".to_string()),
+            base_url: Some("https://evil.example/v1".to_string()),
+            default_text_model: Some("deepseek-v4-pro".to_string()),
+            auth_mode: Some("oauth".to_string()),
+            telemetry: Some(true),
+            ..ConfigToml::default()
+        };
+        project.providers.openrouter.api_key = Some("attacker-openrouter-key".to_string());
+        project.providers.openrouter.base_url = Some("https://evil.example/openrouter".to_string());
+        project.providers.openrouter.model = Some("deepseek/deepseek-v4-pro".to_string());
+
+        base.merge_project_overrides(project);
+
+        assert_eq!(base.provider, ProviderKind::Deepseek);
+        assert_eq!(base.api_key.as_deref(), Some("user-key"));
+        assert_eq!(base.base_url.as_deref(), Some("https://api.deepseek.com"));
+        assert_eq!(base.auth_mode, None);
+        assert_eq!(base.telemetry, None);
+        assert_eq!(
+            base.providers.openrouter.api_key.as_deref(),
+            Some("user-openrouter-key")
+        );
+        assert_eq!(base.providers.openrouter.base_url, None);
+        assert_eq!(base.default_text_model.as_deref(), Some("deepseek-v4-pro"));
+        assert_eq!(
+            base.providers.openrouter.model.as_deref(),
+            Some("deepseek/deepseek-v4-pro")
+        );
+    }
+
+    #[test]
+    fn project_merge_only_tightens_approval_and_sandbox_policy() {
+        let mut strict = ConfigToml {
+            approval_policy: Some("never".to_string()),
+            sandbox_mode: Some("read-only".to_string()),
+            ..ConfigToml::default()
+        };
+        strict.merge_project_overrides(ConfigToml {
+            approval_policy: Some("on-request".to_string()),
+            sandbox_mode: Some("workspace-write".to_string()),
+            ..ConfigToml::default()
+        });
+        assert_eq!(strict.approval_policy.as_deref(), Some("never"));
+        assert_eq!(strict.sandbox_mode.as_deref(), Some("read-only"));
+
+        let mut permissive = ConfigToml {
+            approval_policy: Some("auto".to_string()),
+            sandbox_mode: Some("workspace-write".to_string()),
+            ..ConfigToml::default()
+        };
+        permissive.merge_project_overrides(ConfigToml {
+            approval_policy: Some("never".to_string()),
+            sandbox_mode: Some("read-only".to_string()),
+            ..ConfigToml::default()
+        });
+        assert_eq!(permissive.approval_policy.as_deref(), Some("never"));
+        assert_eq!(permissive.sandbox_mode.as_deref(), Some("read-only"));
+
+        let mut unset = ConfigToml::default();
+        unset.merge_project_overrides(ConfigToml {
+            approval_policy: Some("on-request".to_string()),
+            sandbox_mode: Some("workspace-write".to_string()),
+            ..ConfigToml::default()
+        });
+        assert_eq!(unset.approval_policy, None);
+        assert_eq!(unset.sandbox_mode, None);
+    }
+
     #[test]
     fn list_values_redacts_unicode_api_key_without_byte_slicing() {
         let config = ConfigToml {
@@ -2350,12 +2867,25 @@ mod tests {
             ProviderKind::parse("OPEN_ROUTER"),
             Some(ProviderKind::Openrouter)
         );
+        assert_eq!(
+            ProviderKind::parse("xiaomi-mimo"),
+            Some(ProviderKind::XiaomiMimo)
+        );
+        assert_eq!(
+            ProviderKind::parse("xiaomi"),
+            Some(ProviderKind::XiaomiMimo)
+        );
         assert_eq!(ProviderKind::parse("novita"), Some(ProviderKind::Novita));
         assert_eq!(ProviderKind::parse("Novita"), Some(ProviderKind::Novita));
         assert_eq!(
             ProviderKind::parse("fireworks-ai"),
             Some(ProviderKind::Fireworks)
         );
+        assert_eq!(ProviderKind::parse("kimi"), Some(ProviderKind::Moonshot));
+        assert_eq!(
+            ProviderKind::parse("moonshot-ai"),
+            Some(ProviderKind::Moonshot)
+        );
         assert_eq!(ProviderKind::parse("sg-lang"), Some(ProviderKind::Sglang));
         assert_eq!(ProviderKind::parse("v-llm"), Some(ProviderKind::Vllm));
         assert_eq!(ProviderKind::parse("vllm"), Some(ProviderKind::Vllm));
@@ -2410,6 +2940,22 @@ mod tests {
         assert_eq!(resolved.model, DEFAULT_OPENROUTER_MODEL);
     }
 
+    #[test]
+    fn xiaomi_mimo_provider_defaults_to_canonical_endpoint_and_model() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        let config = ConfigToml {
+            provider: ProviderKind::XiaomiMimo,
+            ..ConfigToml::default()
+        };
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::XiaomiMimo);
+        assert_eq!(resolved.base_url, DEFAULT_XIAOMI_MIMO_BASE_URL);
+        assert_eq!(resolved.model, DEFAULT_XIAOMI_MIMO_MODEL);
+    }
+
     #[test]
     fn novita_provider_defaults_to_canonical_endpoint_and_model() {
         let _lock = env_lock();
@@ -2442,6 +2988,169 @@ mod tests {
         assert_eq!(resolved.model, DEFAULT_FIREWORKS_MODEL);
     }
 
+    #[test]
+    fn moonshot_provider_defaults_to_kimi_k2() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        let config = ConfigToml {
+            provider: ProviderKind::Moonshot,
+            ..ConfigToml::default()
+        };
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.base_url, DEFAULT_MOONSHOT_BASE_URL);
+        assert_eq!(resolved.model, DEFAULT_MOONSHOT_MODEL);
+    }
+
+    #[test]
+    fn moonshot_kimi_oauth_uses_kimi_code_endpoint_and_model() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        let mut config = ConfigToml {
+            provider: ProviderKind::Moonshot,
+            ..ConfigToml::default()
+        };
+        config.providers.moonshot.auth_mode = Some("kimi_oauth".to_string());
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.auth_mode.as_deref(), Some("kimi_oauth"));
+        assert_eq!(resolved.base_url, DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(resolved.model, DEFAULT_KIMI_CODE_MODEL);
+        assert_eq!(resolved.api_key, None);
+        assert_eq!(resolved.api_key_source, None);
+    }
+
+    #[test]
+    fn moonshot_kimi_code_api_key_endpoint_defaults_to_kimi_for_coding() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        let mut config = ConfigToml {
+            provider: ProviderKind::Moonshot,
+            ..ConfigToml::default()
+        };
+        config.providers.moonshot.api_key = Some("kimi-code-key".to_string());
+        config.providers.moonshot.base_url = Some(DEFAULT_KIMI_CODE_BASE_URL.to_string());
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.auth_mode, None);
+        assert_eq!(resolved.base_url, DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(resolved.model, DEFAULT_KIMI_CODE_MODEL);
+        assert_eq!(resolved.api_key.as_deref(), Some("kimi-code-key"));
+        assert_eq!(
+            resolved.api_key_source,
+            Some(RuntimeApiKeySource::ConfigFile)
+        );
+    }
+
+    /// `CODEWHALE_PROVIDER` is the user-facing env alias for switching the
+    /// active provider. It must be honored by the runtime resolver and win
+    /// over a root `provider = "deepseek"` config entry.
+    #[test]
+    fn codewhale_provider_env_switches_active_provider() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        // Safety: test-only env mutation guarded by env_lock().
+        unsafe {
+            env::set_var("CODEWHALE_PROVIDER", "moonshot");
+        }
+        let mut config = ConfigToml {
+            provider: ProviderKind::Deepseek,
+            ..ConfigToml::default()
+        };
+        config.providers.moonshot.api_key = Some("kimi-code-key".to_string());
+        config.providers.moonshot.base_url = Some(DEFAULT_KIMI_CODE_BASE_URL.to_string());
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.base_url, DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(resolved.model, DEFAULT_KIMI_CODE_MODEL);
+        assert_eq!(resolved.api_key.as_deref(), Some("kimi-code-key"));
+    }
+
+    /// When both `CODEWHALE_PROVIDER` and the legacy `DEEPSEEK_PROVIDER`
+    /// are set, the public alias wins — a user adopting `CODEWHALE_*` in a
+    /// fresh shell config is not tripped up by a stale legacy export still
+    /// living in their dotfiles.
+    #[test]
+    fn codewhale_provider_env_wins_over_deepseek_provider_env() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        // Safety: test-only env mutation guarded by env_lock().
+        unsafe {
+            env::set_var("CODEWHALE_PROVIDER", "moonshot");
+            env::set_var("DEEPSEEK_PROVIDER", "openrouter");
+        }
+        let config = ConfigToml {
+            provider: ProviderKind::Deepseek,
+            ..ConfigToml::default()
+        };
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+    }
+
+    /// `CODEWHALE_MODEL` is the user-facing env alias for picking a model
+    /// against the active provider. It must be honored by the runtime
+    /// resolver in place of `DEEPSEEK_MODEL`.
+    #[test]
+    fn codewhale_model_env_alias_overrides_default_for_active_provider() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        // Safety: test-only env mutation guarded by env_lock().
+        unsafe {
+            env::set_var("CODEWHALE_PROVIDER", "moonshot");
+            env::set_var("CODEWHALE_MODEL", "custom-kimi-test-model");
+        }
+        let config = ConfigToml::default();
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.model, "custom-kimi-test-model");
+    }
+
+    #[test]
+    fn blank_codewhale_model_env_alias_does_not_override_default_for_active_provider() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        // Safety: test-only env mutation guarded by env_lock().
+        unsafe {
+            env::set_var("CODEWHALE_PROVIDER", "moonshot");
+            env::set_var("CODEWHALE_MODEL", "   ");
+        }
+        let config = ConfigToml::default();
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.model, DEFAULT_MOONSHOT_MODEL);
+    }
+
+    #[test]
+    fn deepseek_default_text_model_legacy_alias_still_overrides_active_provider_model() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        // Safety: test-only env mutation guarded by env_lock().
+        unsafe {
+            env::set_var("CODEWHALE_PROVIDER", "moonshot");
+            env::set_var("DEEPSEEK_DEFAULT_TEXT_MODEL", "legacy-env-model");
+        }
+        let config = ConfigToml::default();
+
+        let resolved = config.resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::Moonshot);
+        assert_eq!(resolved.model, "legacy-env-model");
+    }
+
     #[test]
     fn wanjie_ark_provider_defaults_to_openai_compatible_endpoint_and_model() {
         let _lock = env_lock();
@@ -2556,6 +3265,25 @@ mod tests {
         assert_eq!(store.gets.lock().unwrap().as_slice(), ["ollama"]);
     }
 
+    #[test]
+    fn moonshot_api_key_mode_can_use_secret_store_by_default() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        let store = Arc::new(RecordingSecretsStore::with_value("secret-store-key"));
+        let secrets = Secrets::new(store.clone());
+        let config = ConfigToml {
+            provider: ProviderKind::Moonshot,
+            ..ConfigToml::default()
+        };
+
+        let resolved =
+            config.resolve_runtime_options_with_secrets(&CliRuntimeOverrides::default(), &secrets);
+
+        assert_eq!(resolved.api_key.as_deref(), Some("secret-store-key"));
+        assert_eq!(resolved.api_key_source, Some(RuntimeApiKeySource::Keyring));
+        assert_eq!(store.gets.lock().unwrap().as_slice(), ["moonshot"]);
+    }
+
     #[test]
     fn loopback_custom_deepseek_base_url_does_not_probe_secret_store_by_default() {
         let _lock = env_lock();
@@ -2632,6 +3360,27 @@ mod tests {
         assert_eq!(resolved.base_url, DEFAULT_OPENROUTER_BASE_URL);
     }
 
+    #[test]
+    fn xiaomi_mimo_env_overrides_provider_key_base_url_and_model() {
+        let _lock = env_lock();
+        let _env = EnvGuard::without_deepseek_runtime_overrides();
+        // Safety: test-only environment mutation guarded by a module mutex.
+        unsafe {
+            env::set_var("DEEPSEEK_PROVIDER", "xiaomi-mimo");
+            env::set_var("MIMO_API_KEY", "mimo-env-key");
+            env::set_var("MIMO_BASE_URL", "https://mimo-gateway.example/v1");
+            env::set_var("MIMO_MODEL", "mimo-v2.5");
+        }
+
+        let resolved =
+            ConfigToml::default().resolve_runtime_options(&CliRuntimeOverrides::default());
+
+        assert_eq!(resolved.provider, ProviderKind::XiaomiMimo);
+        assert_eq!(resolved.api_key.as_deref(), Some("mimo-env-key"));
+        assert_eq!(resolved.base_url, "https://mimo-gateway.example/v1");
+        assert_eq!(resolved.model, "mimo-v2.5");
+    }
+
     #[test]
     fn novita_env_api_key_falls_back_when_config_missing() {
         let _lock = env_lock();
diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml
index debdf425..45853186 100644
--- a/crates/core/Cargo.toml
+++ b/crates/core/Cargo.toml
@@ -9,13 +9,13 @@ description = "Core runtime boundaries for DeepSeek workspace architecture"
 [dependencies]
 anyhow.workspace = true
 chrono.workspace = true
-codewhale-agent = { path = "../agent", version = "0.8.44" }
-codewhale-config = { path = "../config", version = "0.8.44" }
-codewhale-execpolicy = { path = "../execpolicy", version = "0.8.44" }
-codewhale-hooks = { path = "../hooks", version = "0.8.44" }
-codewhale-mcp = { path = "../mcp", version = "0.8.44" }
-codewhale-protocol = { path = "../protocol", version = "0.8.44" }
-codewhale-state = { path = "../state", version = "0.8.44" }
-codewhale-tools = { path = "../tools", version = "0.8.44" }
+codewhale-agent = { path = "../agent", version = "0.8.46" }
+codewhale-config = { path = "../config", version = "0.8.46" }
+codewhale-execpolicy = { path = "../execpolicy", version = "0.8.46" }
+codewhale-hooks = { path = "../hooks", version = "0.8.46" }
+codewhale-mcp = { path = "../mcp", version = "0.8.46" }
+codewhale-protocol = { path = "../protocol", version = "0.8.46" }
+codewhale-state = { path = "../state", version = "0.8.46" }
+codewhale-tools = { path = "../tools", version = "0.8.46" }
 serde_json.workspace = true
 uuid.workspace = true
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
index e6d9f094..472095cc 100644
--- a/crates/core/src/lib.rs
+++ b/crates/core/src/lib.rs
@@ -643,6 +643,7 @@ impl ThreadManager {
             git_branch: None,
             git_origin_url: None,
             memory_mode: None,
+            current_leaf_id: None,
         })
     }
 }
diff --git a/crates/execpolicy/Cargo.toml b/crates/execpolicy/Cargo.toml
index 669759c4..acf2ce21 100644
--- a/crates/execpolicy/Cargo.toml
+++ b/crates/execpolicy/Cargo.toml
@@ -8,5 +8,5 @@ description = "Execution policy and approval model parity for DeepSeek workspace
 
 [dependencies]
 anyhow.workspace = true
-codewhale-protocol = { path = "../protocol", version = "0.8.44" }
+codewhale-protocol = { path = "../protocol", version = "0.8.46" }
 serde.workspace = true
diff --git a/crates/hooks/Cargo.toml b/crates/hooks/Cargo.toml
index a39dc18f..a6a3600e 100644
--- a/crates/hooks/Cargo.toml
+++ b/crates/hooks/Cargo.toml
@@ -10,7 +10,7 @@ description = "Hook dispatch and notifications parity for DeepSeek workspace arc
 anyhow.workspace = true
 async-trait.workspace = true
 chrono.workspace = true
-codewhale-protocol = { path = "../protocol", version = "0.8.44" }
+codewhale-protocol = { path = "../protocol", version = "0.8.46" }
 reqwest.workspace = true
 serde.workspace = true
 serde_json.workspace = true
diff --git a/crates/release/Cargo.toml b/crates/release/Cargo.toml
new file mode 100644
index 00000000..67520686
--- /dev/null
+++ b/crates/release/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "codewhale-release"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Shared CodeWhale release discovery and version comparison helpers"
+
+[dependencies]
+anyhow.workspace = true
+reqwest = { workspace = true, features = ["blocking"] }
+semver.workspace = true
+serde.workspace = true
+serde_json.workspace = true
diff --git a/crates/release/src/lib.rs b/crates/release/src/lib.rs
new file mode 100644
index 00000000..327bb874
--- /dev/null
+++ b/crates/release/src/lib.rs
@@ -0,0 +1,369 @@
+use std::time::Duration;
+
+use anyhow::{Context, Result, bail};
+use serde::Deserialize;
+
+pub const CHECKSUM_MANIFEST_ASSET: &str = "codewhale-artifacts-sha256.txt";
+pub const LATEST_RELEASE_URL: &str =
+    "https://api.github.com/repos/Hmbown/CodeWhale/releases/latest";
+pub const RELEASES_URL: &str =
+    "https://api.github.com/repos/Hmbown/CodeWhale/releases?per_page=100";
+pub const CNB_REPO_URL: &str = "https://cnb.cool/codewhale.net/codewhale";
+pub const RELEASE_BASE_URL_ENV: &str = "CODEWHALE_RELEASE_BASE_URL";
+pub const LEGACY_RELEASE_BASE_URL_ENV: &str = "DEEPSEEK_TUI_RELEASE_BASE_URL";
+pub const DEEPSEEK_RELEASE_BASE_URL_ENV: &str = "DEEPSEEK_RELEASE_BASE_URL";
+pub const CNB_MIRROR_ENV: &str = "CODEWHALE_USE_CNB_MIRROR";
+pub const UPDATE_VERSION_ENV: &str = "DEEPSEEK_TUI_VERSION";
+pub const LEGACY_UPDATE_VERSION_ENV: &str = "DEEPSEEK_VERSION";
+pub const UPDATE_USER_AGENT: &str = "codewhale-updater";
+
+const CNB_RELEASE_ASSET_BASE: &str = "https://cnb.cool/Hmbown/CodeWhale/-/releases";
+const RELEASE_METADATA_TIMEOUT: Duration = Duration::from_secs(5);
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ReleaseChannel {
+    Stable,
+    Beta,
+}
+
+impl ReleaseChannel {
+    pub fn from_beta_flag(beta: bool) -> Self {
+        if beta { Self::Beta } else { Self::Stable }
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Stable => "stable",
+            Self::Beta => "beta",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ReleaseQuery {
+    Mirror { base_url: String, version: String },
+    GitHubLatest { url: &'static str },
+    GitHubReleaseList { url: &'static str },
+}
+
+pub fn resolve_release_query(channel: ReleaseChannel) -> ReleaseQuery {
+    let version = update_version_from_env().unwrap_or_else(|| env!("CARGO_PKG_VERSION").into());
+    if let Some(base_url) = release_base_url_from_env(&version) {
+        return ReleaseQuery::Mirror { base_url, version };
+    }
+
+    match channel {
+        ReleaseChannel::Stable => ReleaseQuery::GitHubLatest {
+            url: LATEST_RELEASE_URL,
+        },
+        ReleaseChannel::Beta => ReleaseQuery::GitHubReleaseList { url: RELEASES_URL },
+    }
+}
+
+pub fn release_base_url_from_env(version: &str) -> Option<String> {
+    for env_name in [
+        RELEASE_BASE_URL_ENV,
+        LEGACY_RELEASE_BASE_URL_ENV,
+        DEEPSEEK_RELEASE_BASE_URL_ENV,
+    ] {
+        if let Ok(value) = std::env::var(env_name) {
+            let trimmed = value.trim().to_string();
+            if !trimmed.is_empty() {
+                return Some(trimmed);
+            }
+        }
+    }
+
+    if std::env::var(CNB_MIRROR_ENV).is_ok() {
+        return Some(cnb_release_base_url(version));
+    }
+    None
+}
+
+pub fn cnb_release_base_url(version: &str) -> String {
+    format!(
+        "{}/v{}",
+        CNB_RELEASE_ASSET_BASE.trim_end_matches('/'),
+        version.trim_start_matches('v')
+    )
+}
+
+pub fn update_version_from_env() -> Option<String> {
+    std::env::var(UPDATE_VERSION_ENV)
+        .ok()
+        .or_else(|| std::env::var(LEGACY_UPDATE_VERSION_ENV).ok())
+        .map(|value| value.trim().trim_start_matches('v').to_string())
+        .filter(|value| !value.is_empty())
+}
+
+pub fn mirror_asset_url(base_url: &str, asset_name: &str) -> String {
+    format!("{}/{}", base_url.trim_end_matches('/'), asset_name)
+}
+
+pub fn update_network_fallback_hint() -> String {
+    format!(
+        "GitHub release downloads may be blocked or slow on this network.\n\
+         For mainland China, use one of these fallback paths:\n\
+           1. Source build from the CNB mirror, installing both shipped binaries:\n\
+              cargo install --git {CNB_REPO_URL} --tag vX.Y.Z codewhale-cli --locked --force\n\
+              cargo install --git {CNB_REPO_URL} --tag vX.Y.Z codewhale-tui --locked --force\n\
+           2. Use a binary asset mirror:\n\
+              {RELEASE_BASE_URL_ENV}=https://<mirror>/<release-assets>/ {UPDATE_VERSION_ENV}=X.Y.Z codewhale update\n\
+         The mirror directory must contain {CHECKSUM_MANIFEST_ASSET} and the platform binaries."
+    )
+}
+
+pub fn fetch_release_json_blocking(url: &str, description: &str) -> Result<String> {
+    let client = reqwest::blocking::Client::builder()
+        .user_agent(UPDATE_USER_AGENT)
+        .timeout(RELEASE_METADATA_TIMEOUT)
+        .build()
+        .context("failed to build release check HTTP client")?;
+    let response = client
+        .get(url)
+        .header(reqwest::header::ACCEPT, "application/vnd.github+json")
+        .send()
+        .with_context(|| format!("failed to fetch {description} from {url}"))?;
+    let status = response.status();
+    let body = response
+        .text()
+        .with_context(|| format!("failed to read {description} response from {url}"));
+    release_response_body(status, body, url, description)
+}
+
+pub async fn fetch_release_json_async(url: &str, description: &str) -> Result<String> {
+    let client = reqwest::Client::builder()
+        .user_agent(UPDATE_USER_AGENT)
+        .timeout(RELEASE_METADATA_TIMEOUT)
+        .build()
+        .context("failed to build release check HTTP client")?;
+    let response = client
+        .get(url)
+        .header(reqwest::header::ACCEPT, "application/vnd.github+json")
+        .send()
+        .await
+        .with_context(|| format!("failed to fetch {description} from {url}"))?;
+    let status = response.status();
+    let body = response
+        .text()
+        .await
+        .with_context(|| format!("failed to read {description} response from {url}"));
+    release_response_body(status, body, url, description)
+}
+
+fn release_response_body(
+    status: reqwest::StatusCode,
+    body: Result<String>,
+    url: &str,
+    description: &str,
+) -> Result<String> {
+    let body = body.with_context(|| format!("failed to read {description} response from {url}"))?;
+    if !status.is_success() {
+        bail!("GitHub release request failed with HTTP {status}: {body}");
+    }
+    Ok(body)
+}
+
+#[derive(Deserialize)]
+struct ReleaseTag {
+    tag_name: String,
+}
+
+#[derive(Deserialize)]
+struct ReleaseListEntry {
+    tag_name: String,
+}
+
+pub fn latest_tag_from_release_json(body: &str) -> Result<String> {
+    let release: ReleaseTag = serde_json::from_str(body).with_context(|| {
+        format!("failed to parse release JSON from GitHub API. Response: {body}")
+    })?;
+    Ok(release.tag_name)
+}
+
+pub fn latest_beta_tag_from_release_list_json(body: &str) -> Result<String> {
+    let releases: Vec<ReleaseListEntry> = serde_json::from_str(body).with_context(|| {
+        format!("failed to parse release list JSON from GitHub API. Response: {body}")
+    })?;
+    releases
+        .into_iter()
+        .find(|release| is_beta_tag(&release.tag_name))
+        .map(|release| release.tag_name)
+        .context("no beta release found in GitHub releases")
+}
+
+pub async fn latest_release_tag_async(channel: ReleaseChannel) -> Result<String> {
+    match resolve_release_query(channel) {
+        ReleaseQuery::Mirror { version, .. } => Ok(format!("v{}", version.trim_start_matches('v'))),
+        ReleaseQuery::GitHubLatest { url } => {
+            let body = fetch_release_json_async(url, "latest release").await?;
+            latest_tag_from_release_json(&body)
+        }
+        ReleaseQuery::GitHubReleaseList { url } => {
+            let body = fetch_release_json_async(url, "release list").await?;
+            latest_beta_tag_from_release_list_json(&body)
+        }
+    }
+}
+
+pub fn latest_release_tag_blocking(channel: ReleaseChannel) -> Result<String> {
+    match resolve_release_query(channel) {
+        ReleaseQuery::Mirror { version, .. } => Ok(format!("v{}", version.trim_start_matches('v'))),
+        ReleaseQuery::GitHubLatest { url } => {
+            let body = fetch_release_json_blocking(url, "latest release")?;
+            latest_tag_from_release_json(&body)
+        }
+        ReleaseQuery::GitHubReleaseList { url } => {
+            let body = fetch_release_json_blocking(url, "release list")?;
+            latest_beta_tag_from_release_list_json(&body)
+        }
+    }
+}
+
+pub fn compare_release_versions(
+    current_version: &str,
+    latest_tag: &str,
+) -> Result<std::cmp::Ordering> {
+    let current = parse_release_version(current_version)
+        .with_context(|| format!("failed to parse current version {current_version:?}"))?;
+    let latest = parse_release_version(latest_tag)
+        .with_context(|| format!("failed to parse latest release tag {latest_tag:?}"))?;
+    Ok(current.cmp(&latest))
+}
+
+pub fn update_is_needed(
+    channel: ReleaseChannel,
+    current_version: &str,
+    latest_tag: &str,
+) -> Result<bool> {
+    let current = parse_release_version(current_version)
+        .with_context(|| format!("failed to parse current version {current_version:?}"))?;
+    let latest = parse_release_version(latest_tag)
+        .with_context(|| format!("failed to parse latest release tag {latest_tag:?}"))?;
+
+    match channel {
+        ReleaseChannel::Stable => Ok(current < latest),
+        ReleaseChannel::Beta => {
+            if current == latest {
+                return Ok(false);
+            }
+            let latest_is_beta = version_is_beta(&latest);
+            let current_is_stable = current.pre.is_empty();
+            let same_release_line = current.major == latest.major
+                && current.minor == latest.minor
+                && current.patch == latest.patch;
+            if current > latest && !(current_is_stable && same_release_line) {
+                return Ok(false);
+            }
+            Ok(latest_is_beta)
+        }
+    }
+}
+
+pub fn parse_release_version(value: &str) -> Result<semver::Version> {
+    let version = value
+        .trim()
+        .trim_start_matches('v')
+        .split_whitespace()
+        .next()
+        .unwrap_or("");
+    semver::Version::parse(version).with_context(|| format!("invalid semver: {value:?}"))
+}
+
+pub fn is_beta_tag(tag_name: &str) -> bool {
+    tag_name.to_ascii_lowercase().contains("beta")
+}
+
+fn version_is_beta(version: &semver::Version) -> bool {
+    version.pre.as_str().to_ascii_lowercase().contains("beta")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cnb_release_base_url_includes_tag_directory() {
+        assert_eq!(
+            cnb_release_base_url("0.8.47"),
+            "https://cnb.cool/Hmbown/CodeWhale/-/releases/v0.8.47"
+        );
+        assert_eq!(
+            cnb_release_base_url("v0.8.47"),
+            "https://cnb.cool/Hmbown/CodeWhale/-/releases/v0.8.47"
+        );
+    }
+
+    #[test]
+    fn stable_update_is_needed_only_when_latest_is_newer() {
+        assert!(update_is_needed(ReleaseChannel::Stable, "0.8.45", "v0.8.46").unwrap());
+        assert!(update_is_needed(ReleaseChannel::Stable, "0.8.45", "v0.9.0-beta.1").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Stable, "0.8.45", "v0.8.45").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Stable, "0.9.0", "v0.9.0-beta.1").unwrap());
+        assert!(
+            !update_is_needed(ReleaseChannel::Stable, "0.9.0-beta.2", "v0.9.0-beta.1").unwrap()
+        );
+    }
+
+    #[test]
+    fn beta_update_allows_switching_from_same_stable_to_beta() {
+        assert!(update_is_needed(ReleaseChannel::Beta, "1.0.0", "v1.0.0-beta.2").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "1.0.0-beta.2", "v1.0.0-beta.2").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "1.0.0-beta.3", "v1.0.0-beta.2").unwrap());
+        assert!(update_is_needed(ReleaseChannel::Beta, "1.0.0-beta.2", "v1.0.0-beta.3").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "2.0.0", "v1.0.0-beta.3").unwrap());
+        assert!(!update_is_needed(ReleaseChannel::Beta, "1.0.0-rc.1", "v1.0.0-beta.3").unwrap());
+    }
+
+    #[test]
+    fn parse_release_version_accepts_tags_and_build_suffixes() {
+        assert_eq!(
+            parse_release_version("v0.9.0-beta.1").unwrap(),
+            semver::Version::parse("0.9.0-beta.1").unwrap()
+        );
+        assert_eq!(
+            parse_release_version("0.8.45 (abcdef123456)").unwrap(),
+            semver::Version::parse("0.8.45").unwrap()
+        );
+    }
+
+    #[test]
+    fn release_version_compare_ignores_v_prefix_and_build_sha() {
+        assert_eq!(
+            compare_release_versions("0.8.39 (eeccf7d)", "v0.8.39").unwrap(),
+            std::cmp::Ordering::Equal
+        );
+        assert_eq!(
+            compare_release_versions("0.8.39", "v0.8.40").unwrap(),
+            std::cmp::Ordering::Less
+        );
+        assert_eq!(
+            compare_release_versions("0.8.40", "v0.8.39").unwrap(),
+            std::cmp::Ordering::Greater
+        );
+    }
+
+    #[test]
+    fn latest_beta_tag_selects_first_beta_release() {
+        let body = r#"[
+          { "tag_name": "v0.9.0" },
+          { "tag_name": "v0.9.0-rc.1" },
+          { "tag_name": "v0.9.0-beta.2" },
+          { "tag_name": "v0.9.0-beta.1" }
+        ]"#;
+        assert_eq!(
+            latest_beta_tag_from_release_list_json(body).unwrap(),
+            "v0.9.0-beta.2"
+        );
+    }
+
+    #[test]
+    fn latest_beta_tag_reports_missing_beta() {
+        let body = r#"[{ "tag_name": "v0.9.0" }]"#;
+        let err = latest_beta_tag_from_release_list_json(body).expect_err("missing beta");
+        assert!(
+            err.to_string().contains("no beta release found"),
+            "unexpected error: {err:#}"
+        );
+    }
+}
diff --git a/crates/secrets/src/lib.rs b/crates/secrets/src/lib.rs
index f2616391..e3020244 100644
--- a/crates/secrets/src/lib.rs
+++ b/crates/secrets/src/lib.rs
@@ -484,9 +484,7 @@ impl Secrets {
 
     /// Resolve a secret with `secret store → env → none` precedence.
     ///
-    /// `name` is the canonical provider name (`"deepseek"`,
-    /// `"openrouter"`, `"novita"`, `"nvidia"`/`"nvidia-nim"`, `"openai"`,
-    /// or `"atlascloud"`).
+    /// `name` is the canonical provider name or a supported provider alias.
     /// Empty strings on either layer are treated as "not set".
     #[must_use]
     pub fn resolve(&self, name: &str) -> Option<String> {
@@ -527,6 +525,9 @@ pub fn env_for(name: &str) -> Option<String> {
     let candidates: &[&str] = match name.to_ascii_lowercase().as_str() {
         "deepseek" => &["DEEPSEEK_API_KEY"],
         "openrouter" => &["OPENROUTER_API_KEY"],
+        "xiaomi-mimo" | "xiaomi_mimo" | "xiaomimimo" | "mimo" | "xiaomi" => {
+            &["XIAOMI_MIMO_API_KEY", "MIMO_API_KEY"]
+        }
         "novita" => &["NOVITA_API_KEY"],
         // NVIDIA NIM falls back to `DEEPSEEK_API_KEY` last because the
         // catalog endpoint accepts the same DeepSeek-issued key when no
@@ -535,11 +536,18 @@ pub fn env_for(name: &str) -> Option<String> {
             &["NVIDIA_API_KEY", "NVIDIA_NIM_API_KEY", "DEEPSEEK_API_KEY"]
         }
         "fireworks" | "fireworks-ai" => &["FIREWORKS_API_KEY"],
+        "moonshot" | "moonshot-ai" | "kimi" | "kimi-k2" => &["MOONSHOT_API_KEY", "KIMI_API_KEY"],
         "sglang" | "sg-lang" => &["SGLANG_API_KEY"],
         "vllm" | "v-llm" => &["VLLM_API_KEY"],
         "ollama" | "ollama-local" => &["OLLAMA_API_KEY"],
         "openai" => &["OPENAI_API_KEY"],
         "atlascloud" | "atlas-cloud" | "atlas_cloud" | "atlas" => &["ATLASCLOUD_API_KEY"],
+        "volcengine" | "volcengine-ark" | "volcengine_ark" | "ark" | "volc-ark"
+        | "volcengineark" => &[
+            "VOLCENGINE_API_KEY",
+            "VOLCENGINE_ARK_API_KEY",
+            "ARK_API_KEY",
+        ],
         "wanjie" | "wanjie-ark" | "wanjie_ark" | "ark-wanjie" | "ark_wanjie" | "wanjieark"
         | "wanjie-maas" | "wanjie_maas" | "wanjiemaas" => &[
             "WANJIE_ARK_API_KEY",
@@ -588,6 +596,8 @@ mod tests {
             "WANJIE_ARK_API_KEY",
             "WANJIE_API_KEY",
             "WANJIE_MAAS_API_KEY",
+            "XIAOMI_MIMO_API_KEY",
+            "MIMO_API_KEY",
             SECRET_BACKEND_ENV,
         ] {
             // Safety: tests serialise on env_lock(); the broader
@@ -765,6 +775,20 @@ mod tests {
         clear_known_envs();
     }
 
+    #[test]
+    fn xiaomi_mimo_env_aliases_resolve() {
+        let _guard = env_lock();
+        clear_known_envs();
+        unsafe { std::env::set_var("MIMO_API_KEY", "mimo-key") };
+
+        assert_eq!(env_for("xiaomi-mimo").as_deref(), Some("mimo-key"));
+        assert_eq!(env_for("xiaomimimo").as_deref(), Some("mimo-key"));
+        assert_eq!(env_for("mimo").as_deref(), Some("mimo-key"));
+        assert_eq!(env_for("xiaomi").as_deref(), Some("mimo-key"));
+
+        clear_known_envs();
+    }
+
     #[test]
     fn fireworks_env_aliases_resolve() {
         let _lock = env_lock();
@@ -778,6 +802,21 @@ mod tests {
         unsafe { std::env::remove_var("FIREWORKS_API_KEY") };
     }
 
+    #[test]
+    fn moonshot_kimi_env_aliases_resolve() {
+        let _lock = env_lock();
+        clear_known_envs();
+        // Safety: env mutation guarded by env_lock().
+        unsafe { std::env::set_var("KIMI_API_KEY", "kimi-key") };
+
+        assert_eq!(env_for("moonshot").as_deref(), Some("kimi-key"));
+        assert_eq!(env_for("moonshot-ai").as_deref(), Some("kimi-key"));
+        assert_eq!(env_for("kimi").as_deref(), Some("kimi-key"));
+        assert_eq!(env_for("kimi-k2").as_deref(), Some("kimi-key"));
+        // Safety: env mutation guarded by env_lock().
+        unsafe { std::env::remove_var("KIMI_API_KEY") };
+    }
+
     #[test]
     fn sglang_env_aliases_resolve() {
         let _lock = env_lock();
diff --git a/crates/state/src/lib.rs b/crates/state/src/lib.rs
index 9bad8a16..7d4eace8 100644
--- a/crates/state/src/lib.rs
+++ b/crates/state/src/lib.rs
@@ -53,6 +53,7 @@ pub struct ThreadMetadata {
     pub git_branch: Option<String>,
     pub git_origin_url: Option<String>,
     pub memory_mode: Option<String>,
+    pub current_leaf_id: Option<i64>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -71,6 +72,7 @@ pub struct MessageRecord {
     pub content: String,
     pub item: Option<Value>,
     pub created_at: i64,
+    pub parent_entry_id: Option<i64>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -162,82 +164,113 @@ impl StateStore {
 
     fn init_schema(&self) -> Result<()> {
         let conn = self.conn()?;
-        conn.execute_batch(
-            r#"
-            CREATE TABLE IF NOT EXISTS threads (
-                id TEXT PRIMARY KEY,
-                rollout_path TEXT,
-                preview TEXT NOT NULL,
-                ephemeral INTEGER NOT NULL,
-                model_provider TEXT NOT NULL,
-                created_at INTEGER NOT NULL,
-                updated_at INTEGER NOT NULL,
-                status TEXT NOT NULL,
-                path TEXT,
-                cwd TEXT NOT NULL,
-                cli_version TEXT NOT NULL,
-                source TEXT NOT NULL,
-                title TEXT,
-                sandbox_policy TEXT,
-                approval_mode TEXT,
-                archived INTEGER NOT NULL DEFAULT 0,
-                archived_at INTEGER,
-                git_sha TEXT,
-                git_branch TEXT,
-                git_origin_url TEXT,
-                memory_mode TEXT
-            );
-            CREATE INDEX IF NOT EXISTS idx_threads_updated_at ON threads(updated_at DESC);
-            CREATE INDEX IF NOT EXISTS idx_threads_archived_at ON threads(archived_at DESC);
-            CREATE INDEX IF NOT EXISTS idx_threads_archived_updated ON threads(archived, updated_at DESC);
+        let user_version: u32 = conn.query_row("PRAGMA user_version;", [], |row| row.get(0))?;
+        if user_version == 0 {
+            conn.execute_batch(
+                r#"
+                BEGIN;
+                CREATE TABLE IF NOT EXISTS threads (
+                    id TEXT PRIMARY KEY,
+                    rollout_path TEXT,
+                    preview TEXT NOT NULL,
+                    ephemeral INTEGER NOT NULL,
+                    model_provider TEXT NOT NULL,
+                    created_at INTEGER NOT NULL,
+                    updated_at INTEGER NOT NULL,
+                    status TEXT NOT NULL,
+                    path TEXT,
+                    cwd TEXT NOT NULL,
+                    cli_version TEXT NOT NULL,
+                    source TEXT NOT NULL,
+                    title TEXT,
+                    sandbox_policy TEXT,
+                    approval_mode TEXT,
+                    archived INTEGER NOT NULL DEFAULT 0,
+                    archived_at INTEGER,
+                    git_sha TEXT,
+                    git_branch TEXT,
+                    git_origin_url TEXT,
+                    memory_mode TEXT
+                );
+                CREATE INDEX IF NOT EXISTS idx_threads_updated_at ON threads(updated_at DESC);
+                CREATE INDEX IF NOT EXISTS idx_threads_archived_at ON threads(archived_at DESC);
+                CREATE INDEX IF NOT EXISTS idx_threads_archived_updated ON threads(archived, updated_at DESC);
 
-            CREATE TABLE IF NOT EXISTS thread_dynamic_tools (
-                thread_id TEXT NOT NULL,
-                position INTEGER NOT NULL,
-                name TEXT NOT NULL,
-                description TEXT,
-                input_schema TEXT NOT NULL,
-                PRIMARY KEY (thread_id, position),
-                FOREIGN KEY(thread_id) REFERENCES threads(id) ON DELETE CASCADE
-            );
+                CREATE TABLE IF NOT EXISTS thread_dynamic_tools (
+                    thread_id TEXT NOT NULL,
+                    position INTEGER NOT NULL,
+                    name TEXT NOT NULL,
+                    description TEXT,
+                    input_schema TEXT NOT NULL,
+                    PRIMARY KEY (thread_id, position),
+                    FOREIGN KEY(thread_id) REFERENCES threads(id) ON DELETE CASCADE
+                );
 
-            CREATE TABLE IF NOT EXISTS messages (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                thread_id TEXT NOT NULL,
-                role TEXT NOT NULL,
-                content TEXT NOT NULL,
-                item_json TEXT,
-                created_at INTEGER NOT NULL,
-                FOREIGN KEY(thread_id) REFERENCES threads(id) ON DELETE CASCADE
-            );
-            CREATE INDEX IF NOT EXISTS idx_messages_thread_created_at ON messages(thread_id, created_at ASC);
+                CREATE TABLE IF NOT EXISTS messages (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    thread_id TEXT NOT NULL,
+                    role TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    item_json TEXT,
+                    created_at INTEGER NOT NULL,
+                    FOREIGN KEY(thread_id) REFERENCES threads(id) ON DELETE CASCADE
+                );
+                CREATE INDEX IF NOT EXISTS idx_messages_thread_created_at ON messages(thread_id, created_at ASC);
 
-            CREATE TABLE IF NOT EXISTS checkpoints (
-                thread_id TEXT NOT NULL,
-                checkpoint_id TEXT NOT NULL,
-                state_json TEXT NOT NULL,
-                created_at INTEGER NOT NULL,
-                PRIMARY KEY(thread_id, checkpoint_id),
-                FOREIGN KEY(thread_id) REFERENCES threads(id) ON DELETE CASCADE
-            );
-            CREATE INDEX IF NOT EXISTS idx_checkpoints_thread_created_at ON checkpoints(thread_id, created_at DESC);
+                CREATE TABLE IF NOT EXISTS checkpoints (
+                    thread_id TEXT NOT NULL,
+                    checkpoint_id TEXT NOT NULL,
+                    state_json TEXT NOT NULL,
+                    created_at INTEGER NOT NULL,
+                    PRIMARY KEY(thread_id, checkpoint_id),
+                    FOREIGN KEY(thread_id) REFERENCES threads(id) ON DELETE CASCADE
+                );
+                CREATE INDEX IF NOT EXISTS idx_checkpoints_thread_created_at ON checkpoints(thread_id, created_at DESC);
 
-            CREATE TABLE IF NOT EXISTS jobs (
-                id TEXT PRIMARY KEY,
-                name TEXT NOT NULL,
-                status TEXT NOT NULL,
-                progress INTEGER,
-                detail TEXT,
-                created_at INTEGER NOT NULL,
-                updated_at INTEGER NOT NULL
-            );
-            CREATE INDEX IF NOT EXISTS idx_jobs_updated_at ON jobs(updated_at DESC);
-            "#,
-        )
-        .context("failed to initialize thread schema")?;
+                CREATE TABLE IF NOT EXISTS jobs (
+                    id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    progress INTEGER,
+                    detail TEXT,
+                    created_at INTEGER NOT NULL,
+                    updated_at INTEGER NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS idx_jobs_updated_at ON jobs(updated_at DESC);
+
+                -- Add parent_entry_id column, and set to last message before current message
+                ALTER TABLE messages ADD COLUMN parent_entry_id INTEGER NULL;
+                UPDATE messages
+                    SET parent_entry_id = (
+                        SELECT m2.id
+                        FROM messages m2
+                        WHERE m2.created_at < messages.created_at AND m2.thread_id = messages.thread_id
+                        ORDER BY m2.id DESC
+                        LIMIT 1
+                    );
+                CREATE INDEX idx_messages_parent_entry_id ON messages(parent_entry_id);
+
+                -- Add current_leaf_id column, and set to last message in thread
+                ALTER TABLE threads ADD COLUMN current_leaf_id INTEGER NULL;
+                UPDATE threads
+                    SET current_leaf_id = (
+                        SELECT m.id
+                        FROM messages m
+                        WHERE m.thread_id = threads.id
+                        ORDER BY m.id DESC
+                        LIMIT 1
+                    );
+
+                PRAGMA user_version = 1;
+                COMMIT;
+                "#,
+            )
+            .context("failed to initialize thread schema")?;
+        }
         Ok(())
     }
 
+    /// Upsert thread metadata(will not set current_leaf_id)
     pub fn upsert_thread(&self, thread: &ThreadMetadata) -> Result<()> {
         let conn = self.conn()?;
         conn.execute(
@@ -314,7 +347,7 @@ impl StateStore {
             r#"
             SELECT id, rollout_path, preview, ephemeral, model_provider, created_at, updated_at, status, path, cwd,
                    cli_version, source, title, sandbox_policy, approval_mode, archived, archived_at,
-                   git_sha, git_branch, git_origin_url, memory_mode
+                   git_sha, git_branch, git_origin_url, memory_mode, current_leaf_id
             FROM threads
             WHERE id = ?1
             "#,
@@ -328,9 +361,9 @@ impl StateStore {
     pub fn list_threads(&self, filters: ThreadListFilters) -> Result<Vec<ThreadMetadata>> {
         let conn = self.conn()?;
         let sql = if filters.include_archived {
-            "SELECT id, rollout_path, preview, ephemeral, model_provider, created_at, updated_at, status, path, cwd, cli_version, source, title, sandbox_policy, approval_mode, archived, archived_at, git_sha, git_branch, git_origin_url, memory_mode FROM threads ORDER BY updated_at DESC LIMIT ?1"
+            "SELECT id, rollout_path, preview, ephemeral, model_provider, created_at, updated_at, status, path, cwd, cli_version, source, title, sandbox_policy, approval_mode, archived, archived_at, git_sha, git_branch, git_origin_url, memory_mode, current_leaf_id FROM threads ORDER BY updated_at DESC LIMIT ?1"
         } else {
-            "SELECT id, rollout_path, preview, ephemeral, model_provider, created_at, updated_at, status, path, cwd, cli_version, source, title, sandbox_policy, approval_mode, archived, archived_at, git_sha, git_branch, git_origin_url, memory_mode FROM threads WHERE archived = 0 ORDER BY updated_at DESC LIMIT ?1"
+            "SELECT id, rollout_path, preview, ephemeral, model_provider, created_at, updated_at, status, path, cwd, cli_version, source, title, sandbox_policy, approval_mode, archived, archived_at, git_sha, git_branch, git_origin_url, memory_mode, current_leaf_id FROM threads WHERE archived = 0 ORDER BY updated_at DESC LIMIT ?1"
         };
 
         let mut stmt = conn.prepare(sql).context("failed to prepare list query")?;
@@ -398,6 +431,54 @@ impl StateStore {
         .map(Option::flatten)
     }
 
+    pub fn list_leaf_messages(&self, thread_id: &str) -> Result<Vec<MessageRecord>> {
+        let conn = self.conn()?;
+        let mut stmt = conn
+            .prepare(
+                r#"
+                SELECT m1.id, m1.thread_id, m1.role, m1.content, m1.item_json, m1.created_at, m1.parent_entry_id
+                FROM messages m1
+                LEFT JOIN messages m2 ON m1.id = m2.parent_entry_id
+                WHERE m1.thread_id = ?1 AND m2.id IS NULL
+                "#,
+            )
+            .context("failed to prepare message listing query")?;
+        let mut rows = stmt
+            .query(params![thread_id])
+            .with_context(|| format!("failed to list leaf messages for thread {thread_id}"))?;
+        let mut out = Vec::new();
+        while let Some(row) = rows.next().context("failed to iterate message rows")? {
+            let item_json: Option<String> = row.get(4).context("failed to read item json")?;
+            let item = item_json
+                .as_deref()
+                .map(serde_json::from_str)
+                .transpose()
+                .with_context(|| {
+                    format!("failed to parse message item json in thread {thread_id}")
+                })?;
+            out.push(MessageRecord {
+                id: row.get(0).context("failed to read message id")?,
+                thread_id: row.get(1).context("failed to read message thread id")?,
+                role: row.get(2).context("failed to read message role")?,
+                content: row.get(3).context("failed to read message content")?,
+                item,
+                created_at: row.get(5).context("failed to read message timestamp")?,
+                parent_entry_id: row.get(6).context("failed to read parent entry id")?,
+            });
+        }
+        Ok(out)
+    }
+
+    pub fn set_current_leaf_id(&self, thread_id: &str, current_leaf_id: &str) -> Result<()> {
+        let conn = self.conn()?;
+        conn.execute(
+            "UPDATE threads SET current_leaf_id = ?1 WHERE id = ?2",
+            params![current_leaf_id, thread_id],
+        )
+        .context("failed to update thread current leaf id")?;
+        Ok(())
+    }
+
     pub fn persist_dynamic_tools(
         &self,
         thread_id: &str,
@@ -464,19 +545,52 @@ impl StateStore {
         content: &str,
         item: Option<Value>,
     ) -> Result<i64> {
-        let conn = self.conn()?;
+        let mut conn = self.conn()?;
         let created_at = Utc::now().timestamp();
         let item_json = item
             .as_ref()
             .map(serde_json::to_string)
             .transpose()
             .context("failed to serialize message item payload")?;
-        conn.execute(
-            "INSERT INTO messages(thread_id, role, content, item_json, created_at) VALUES (?1, ?2, ?3, ?4, ?5)",
-            params![thread_id, role, content, item_json, created_at],
+
+        let tx = conn
+            .transaction()
+            .context("failed to begin append message transaction")?;
+
+        let current_leaf_id: Option<i64> = tx
+            .query_row(
+                "SELECT current_leaf_id FROM threads WHERE id = ?1",
+                params![thread_id],
+                |row| row.get(0),
+            )
+            .with_context(|| {
+                format!("failed to query thread current leaf id for thread {thread_id}")
+            })?;
+
+        let next_leaf_id: i64 = tx.query_row(
+            r#"
+                INSERT INTO messages(thread_id, role, content, item_json, created_at, parent_entry_id)
+                SELECT ?1, ?2, ?3, ?4, ?5, ?6
+                RETURNING id
+            "#, params![thread_id, role, content, item_json, created_at, current_leaf_id], |row| row.get(0)
+        ).with_context(|| format!("failed to append message for thread {thread_id}"))?;
+
+        tx.execute(
+            r#"
+            UPDATE threads
+            SET current_leaf_id = ?1
+            WHERE id = ?2;
+            "#,
+            params![next_leaf_id, thread_id],
         )
-        .with_context(|| format!("failed to append message for thread {thread_id}"))?;
-        Ok(conn.last_insert_rowid())
+        .with_context(|| {
+            format!("failed to update thread current leaf id for thread {thread_id}")
+        })?;
+
+        tx.commit()
+            .context("failed to commit append message transaction")?;
+
+        Ok(next_leaf_id)
     }
 
     pub fn list_messages(
@@ -488,11 +602,30 @@ impl StateStore {
         let limit = i64::try_from(limit.unwrap_or(500)).unwrap_or(500);
         let mut stmt = conn
             .prepare(
-                "SELECT id, thread_id, role, content, item_json, created_at FROM messages WHERE thread_id = ?1 ORDER BY created_at ASC LIMIT ?2",
+                r#"  
+                WITH RECURSIVE
+                    leaf_id AS (
+                        SELECT current_leaf_id FROM threads WHERE id = ?1
+                    ),
+                    ancestors AS (
+                        SELECT id, thread_id, role, content, item_json, created_at, parent_entry_id, 0 AS depth
+                        FROM messages
+                        WHERE id = (SELECT current_leaf_id FROM leaf_id)
+
+                        UNION ALL
+
+                        SELECT m.id, m.thread_id, m.role, m.content, m.item_json, m.created_at, m.parent_entry_id, a.depth + 1
+                        FROM messages m
+                        JOIN ancestors a ON m.id = a.parent_entry_id
+                        WHERE a.depth < ?2
+                    )
+                    SELECT id, thread_id, role, content, item_json, created_at, parent_entry_id FROM ancestors
+                    ORDER BY depth DESC
+                "#
             )
             .context("failed to prepare message listing query")?;
         let mut rows = stmt
-            .query(params![thread_id, limit])
+            .query(params![thread_id, limit - 1])
             .with_context(|| format!("failed to list messages for thread {thread_id}"))?;
         let mut out = Vec::new();
         while let Some(row) = rows.next().context("failed to iterate message rows")? {
@@ -511,18 +644,95 @@ impl StateStore {
                 content: row.get(3).context("failed to read message content")?,
                 item,
                 created_at: row.get(5).context("failed to read message timestamp")?,
+                parent_entry_id: row.get(6).context("failed to read parent entry id")?,
             });
         }
         Ok(out)
     }
 
+    pub fn fork_at_message(
+        &self,
+        message_id: &str,
+        role: &str,
+        content: &str,
+        item: Option<Value>,
+    ) -> Result<i64> {
+        let mut conn = self.conn()?;
+        let created_at = Utc::now().timestamp();
+        let item_json = item
+            .as_ref()
+            .map(serde_json::to_string)
+            .transpose()
+            .context("failed to serialize message item payload")?;
+
+        let tx = conn
+            .transaction()
+            .context("failed to begin fork message transaction")?;
+
+        let thread_id: String = tx
+            .query_row(
+                "SELECT thread_id FROM messages WHERE id = ?1",
+                params![message_id],
+                |row| row.get(0),
+            )
+            .with_context(|| format!("failed to query thread id for message {message_id}"))?;
+
+        let next_leaf_id: i64 = tx.query_row(
+            r#"
+                INSERT INTO messages(thread_id, role, content, item_json, created_at, parent_entry_id)
+                SELECT ?1, ?2, ?3, ?4, ?5, ?6
+                RETURNING id
+            "#, params![thread_id, role, content, item_json, created_at, message_id], |row| row.get(0)
+        ).with_context(|| format!("failed to fork at message for thread {:?}", thread_id))?;
+
+        tx.execute(
+            r#"
+            UPDATE threads
+            SET current_leaf_id = ?1
+            WHERE id = ?2;
+            "#,
+            params![next_leaf_id, thread_id],
+        )
+        .with_context(|| {
+            format!(
+                "failed to update thread current leaf id for thread {:?}",
+                thread_id
+            )
+        })?;
+
+        tx.commit()
+            .context("failed to commit fork message transaction")?;
+
+        Ok(next_leaf_id)
+    }
+
     pub fn clear_messages(&self, thread_id: &str) -> Result<usize> {
-        let conn = self.conn()?;
-        conn.execute(
-            "DELETE FROM messages WHERE thread_id = ?1",
+        let mut conn = self.conn()?;
+        let tx = conn
+            .transaction()
+            .context("failed to begin clear messages transaction")?;
+
+        tx.execute(
+            r#"
+            UPDATE threads
+            SET current_leaf_id = NULL
+            WHERE id = ?1;
+            "#,
             params![thread_id],
         )
-        .with_context(|| format!("failed to clear messages for thread {thread_id}"))
+        .with_context(|| format!("failed to clear messages for thread {thread_id}"))?;
+        let result = tx
+            .execute(
+                r#"
+                DELETE FROM messages WHERE thread_id = ?1
+                "#,
+                params![thread_id],
+            )
+            .with_context(|| format!("failed to clear messages for thread {thread_id}"))?;
+        tx.commit()
+            .context("failed to commit clear messages transaction")?;
+
+        Ok(result)
     }
 
     pub fn save_checkpoint(
@@ -946,5 +1156,6 @@ fn row_to_thread(row: &rusqlite::Row<'_>) -> rusqlite::Result<ThreadMetadata> {
         git_branch: row.get(18)?,
         git_origin_url: row.get(19)?,
         memory_mode: row.get(20)?,
+        current_leaf_id: row.get(21)?,
     })
 }
diff --git a/crates/state/tests/parity_state.rs b/crates/state/tests/parity_state.rs
index d666f50b..70bbe661 100644
--- a/crates/state/tests/parity_state.rs
+++ b/crates/state/tests/parity_state.rs
@@ -1,6 +1,7 @@
 use std::path::PathBuf;
 
 use codewhale_state::{SessionSource, StateStore, ThreadListFilters, ThreadMetadata, ThreadStatus};
+use rusqlite::Connection;
 
 fn temp_state_path(label: &str) -> PathBuf {
     std::env::temp_dir().join(format!(
@@ -38,6 +39,7 @@ fn upsert_and_resume_thread_metadata() {
         git_branch: None,
         git_origin_url: None,
         memory_mode: Some("extended".to_string()),
+        current_leaf_id: None,
     };
     store.upsert_thread(&thread).expect("upsert thread");
 
@@ -70,3 +72,212 @@ fn upsert_and_resume_thread_metadata() {
         .expect("list threads");
     assert!(!listed.is_empty());
 }
+
+#[test]
+fn init_schema_migration() {
+    let path = temp_state_path("init_schema_migration");
+    let conn = Connection::open(&path).expect("open state db");
+    conn.execute_batch(
+        r#"
+        CREATE TABLE IF NOT EXISTS threads (
+            id TEXT PRIMARY KEY,
+            rollout_path TEXT,
+            preview TEXT NOT NULL,
+            ephemeral INTEGER NOT NULL,
+            model_provider TEXT NOT NULL,
+            created_at INTEGER NOT NULL,
+            updated_at INTEGER NOT NULL,
+            status TEXT NOT NULL,
+            path TEXT,
+            cwd TEXT NOT NULL,
+            cli_version TEXT NOT NULL,
+            source TEXT NOT NULL,
+            title TEXT,
+            sandbox_policy TEXT,
+            approval_mode TEXT,
+            archived INTEGER NOT NULL DEFAULT 0,
+            archived_at INTEGER,
+            git_sha TEXT,
+            git_branch TEXT,
+            git_origin_url TEXT,
+            memory_mode TEXT
+        );
+        CREATE TABLE IF NOT EXISTS messages (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            thread_id TEXT NOT NULL,
+            role TEXT NOT NULL,
+            content TEXT NOT NULL,
+            item_json TEXT,
+            created_at INTEGER NOT NULL,
+            FOREIGN KEY(thread_id) REFERENCES threads(id) ON DELETE CASCADE
+        );
+        INSERT INTO threads (
+            id, preview, ephemeral, model_provider, created_at, updated_at, status, cwd, cli_version, source, archived
+        )
+        VALUES (
+            'thread-test-1', 'hello', false, 'deepseek', 0, 0, 'running', '/tmp/project', '0.0.0-test', 'interactive', false
+        );
+        INSERT INTO messages (thread_id, role, content, created_at) VALUES 
+        ('thread-test-1', 'foo0', 'bar0', 0),
+        ('thread-test-1', 'foo1', 'bar1', 1),
+        ('thread-test-1', 'foo2', 'bar2', 2);
+        "#,
+    )
+    .expect("init schema migration");
+
+    let store = StateStore::open(Some(path.clone())).expect("open state store");
+    let thread = store
+        .get_thread("thread-test-1")
+        .expect("read thread")
+        .unwrap();
+    assert_eq!(thread.id, "thread-test-1");
+    assert_eq!(thread.preview, "hello");
+    assert!(!thread.ephemeral);
+    assert_eq!(thread.model_provider, "deepseek");
+    assert_eq!(thread.created_at, 0);
+    assert_eq!(thread.updated_at, 0);
+    assert_eq!(thread.status, ThreadStatus::Running);
+    assert_eq!(thread.cwd, PathBuf::from("/tmp/project"));
+    assert_eq!(thread.cli_version, "0.0.0-test");
+    assert_eq!(thread.source, SessionSource::Interactive);
+    assert!(thread.current_leaf_id.is_some());
+
+    let messages = store
+        .list_messages("thread-test-1", None)
+        .expect("list messages");
+    assert_eq!(messages.len(), 3);
+    for (i, message) in messages.iter().enumerate() {
+        assert_eq!(message.thread_id, "thread-test-1");
+        assert_eq!(message.role, format!("foo{}", i));
+        assert_eq!(message.content, format!("bar{}", i));
+        assert_eq!(message.created_at, i as i64);
+    }
+
+    // Test idempotent
+    StateStore::open(Some(path.clone())).expect("open state store");
+}
+
+#[test]
+fn test_fork() {
+    let path = temp_state_path("test_fork");
+    let store = StateStore::open(Some(path.clone())).expect("open state store");
+    let now = chrono::Utc::now().timestamp();
+    let thread = ThreadMetadata {
+        id: "thread-test-1".to_string(),
+        rollout_path: Some(PathBuf::from("/tmp/rollout.jsonl")),
+        preview: "hello".to_string(),
+        ephemeral: false,
+        model_provider: "deepseek".to_string(),
+        created_at: now,
+        updated_at: now,
+        status: ThreadStatus::Running,
+        path: Some(PathBuf::from("/tmp/project")),
+        cwd: PathBuf::from("/tmp/project"),
+        cli_version: "0.0.0-test".to_string(),
+        source: SessionSource::Interactive,
+        name: Some("Test Thread".to_string()),
+        sandbox_policy: Some("workspace-write".to_string()),
+        approval_mode: Some("on-request".to_string()),
+        archived: false,
+        archived_at: None,
+        git_sha: None,
+        git_branch: None,
+        git_origin_url: None,
+        memory_mode: Some("extended".to_string()),
+        current_leaf_id: None,
+    };
+
+    store.upsert_thread(&thread).expect("upsert thread");
+    store
+        .append_message("thread-test-1", "foo0", "bar0", None)
+        .expect("append message");
+    store
+        .append_message("thread-test-1", "foo1", "bar1", None)
+        .expect("append message");
+    store
+        .append_message("thread-test-1", "foo2", "bar2", None)
+        .expect("append message");
+    store
+        .append_message("thread-test-1", "foo3", "bar3", None)
+        .expect("append message");
+    store
+        .append_message("thread-test-1", "foo4", "bar4", None)
+        .expect("append message");
+
+    let messages = store
+        .list_messages("thread-test-1", None)
+        .expect("list messages");
+    assert_eq!(messages.len(), 5);
+    let ids = messages
+        .iter()
+        .enumerate()
+        .map(|(i, message)| {
+            assert_eq!(message.thread_id, "thread-test-1");
+            assert_eq!(message.role, format!("foo{}", i));
+            assert_eq!(message.content, format!("bar{}", i));
+            message.id.to_string()
+        })
+        .collect::<Vec<_>>();
+
+    store.upsert_thread(&thread).expect("upsert thread");
+
+    store
+        .fork_at_message(&ids[2], "foo5", "bar5", None)
+        .expect("fork at message");
+    let messages = store
+        .list_messages("thread-test-1", None)
+        .expect("list messages");
+    assert_eq!(messages.len(), 4);
+    const LIST_1: [i64; 4] = [0, 1, 2, 5];
+    messages
+        .iter()
+        .zip(LIST_1.iter())
+        .for_each(|(message, &i)| {
+            assert_eq!(message.thread_id, "thread-test-1");
+            assert_eq!(message.role, format!("foo{}", i));
+            assert_eq!(message.content, format!("bar{}", i));
+        });
+    let leaves = store
+        .list_leaf_messages("thread-test-1")
+        .expect("list leaf messages");
+    assert_eq!(leaves.len(), 2);
+
+    store
+        .set_current_leaf_id("thread-test-1", &ids[4])
+        .expect("set current leaf id");
+    store
+        .append_message("thread-test-1", "foo6", "bar6", None)
+        .expect("append message");
+    let messages = store
+        .list_messages("thread-test-1", None)
+        .expect("list messages");
+    assert_eq!(messages.len(), 6);
+    const LIST_2: [i64; 6] = [0, 1, 2, 3, 4, 6];
+    messages
+        .iter()
+        .zip(LIST_2.iter())
+        .for_each(|(message, &i)| {
+            assert_eq!(message.thread_id, "thread-test-1");
+            assert_eq!(message.role, format!("foo{}", i));
+            assert_eq!(message.content, format!("bar{}", i));
+        });
+
+    let leaves = store
+        .list_leaf_messages("thread-test-1")
+        .expect("list leaf messages");
+    assert_eq!(leaves.len(), 2);
+
+    store
+        .clear_messages("thread-test-1")
+        .expect("clear messages");
+    let leaves = store
+        .list_leaf_messages("thread-test-1")
+        .expect("list leaf messages");
+    assert_eq!(leaves.len(), 0);
+    let thread = store
+        .get_thread("thread-test-1")
+        .expect("get thread")
+        .unwrap();
+    dbg!(&thread);
+    assert!(thread.current_leaf_id.is_none());
+}
diff --git a/crates/tools/Cargo.toml b/crates/tools/Cargo.toml
index 9059c344..2be5cc0d 100644
--- a/crates/tools/Cargo.toml
+++ b/crates/tools/Cargo.toml
@@ -9,7 +9,7 @@ description = "Tool invocation lifecycle, schema validation, and scheduler paral
 [dependencies]
 anyhow.workspace = true
 async-trait.workspace = true
-codewhale-protocol = { path = "../protocol", version = "0.8.44" }
+codewhale-protocol = { path = "../protocol", version = "0.8.46" }
 serde.workspace = true
 serde_json.workspace = true
 tokio.workspace = true
diff --git a/crates/tools/src/lib.rs b/crates/tools/src/lib.rs
index a7179410..b0ffc55b 100644
--- a/crates/tools/src/lib.rs
+++ b/crates/tools/src/lib.rs
@@ -8,7 +8,11 @@ use async_trait::async_trait;
 use codewhale_protocol::{ToolKind, ToolOutput, ToolPayload};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
-use tokio::sync::RwLock;
+use tokio::sync::{OwnedRwLockReadGuard, OwnedRwLockWriteGuard, RwLock};
+
+tokio::task_local! {
+    static TOOL_EXECUTION_LOCK_HELD: ();
+}
 
 /// Capabilities that a tool may have or require.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -309,9 +313,40 @@ pub trait ToolHandler: Send + Sync {
     ) -> std::result::Result<ToolOutput, FunctionCallError>;
 }
 
-#[derive(Debug, Default)]
+#[derive(Debug)]
 pub struct ToolCallRuntime {
-    pub parallel_execution: Arc<RwLock<()>>,
+    /// Preserve read/write tool execution semantics: parallel-safe tools may
+    /// overlap, while serial tools run exclusively.
+    execution_lock: Arc<RwLock<()>>,
+}
+
+impl Default for ToolCallRuntime {
+    fn default() -> Self {
+        Self {
+            execution_lock: Arc::new(RwLock::new(())),
+        }
+    }
+}
+
+#[derive(Debug)]
+enum ToolExecutionGuard {
+    Parallel(#[allow(dead_code)] OwnedRwLockReadGuard<()>),
+    Serial(#[allow(dead_code)] OwnedRwLockWriteGuard<()>),
+    Reentrant,
+}
+
+impl ToolCallRuntime {
+    async fn acquire(&self, supports_parallel: bool) -> ToolExecutionGuard {
+        if TOOL_EXECUTION_LOCK_HELD.try_with(|_| ()).is_ok() {
+            return ToolExecutionGuard::Reentrant;
+        }
+
+        if supports_parallel {
+            ToolExecutionGuard::Parallel(self.execution_lock.clone().read_owned().await)
+        } else {
+            ToolExecutionGuard::Serial(self.execution_lock.clone().write_owned().await)
+        }
+    }
 }
 
 #[derive(Default)]
@@ -379,15 +414,17 @@ impl ToolRegistry {
             source: call.source,
         };
 
-        if configured.supports_parallel_tool_calls {
-            let _guard = self.runtime.parallel_execution.read().await;
-            self.execute_with_timeout(handler, configured.spec.timeout_ms, invocation)
-                .await
-        } else {
-            let _guard = self.runtime.parallel_execution.write().await;
-            self.execute_with_timeout(handler, configured.spec.timeout_ms, invocation)
-                .await
-        }
+        let _guard = self
+            .runtime
+            .acquire(configured.supports_parallel_tool_calls)
+            .await;
+
+        TOOL_EXECUTION_LOCK_HELD
+            .scope(
+                (),
+                self.execute_with_timeout(handler, configured.spec.timeout_ms, invocation),
+            )
+            .await
     }
 
     async fn execute_with_timeout(
diff --git a/crates/tools/tests/parity_tools.rs b/crates/tools/tests/parity_tools.rs
index fb08753b..ef525ba4 100644
--- a/crates/tools/tests/parity_tools.rs
+++ b/crates/tools/tests/parity_tools.rs
@@ -1,4 +1,5 @@
-use std::sync::Arc;
+use std::sync::{Arc, OnceLock};
+use std::time::Duration;
 
 use async_trait::async_trait;
 use codewhale_protocol::{ToolKind, ToolOutput, ToolPayload};
@@ -6,6 +7,7 @@ use codewhale_tools::{
     ToolCall, ToolCallSource, ToolHandler, ToolInvocation, ToolRegistry, ToolSpec,
 };
 use serde_json::json;
+use tokio::sync::Notify;
 
 struct EchoHandler;
 
@@ -33,6 +35,64 @@ impl ToolHandler for EchoHandler {
     }
 }
 
+struct BlockingHandler {
+    started: Arc<Notify>,
+    release: Arc<Notify>,
+}
+
+#[async_trait]
+impl ToolHandler for BlockingHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(
+        &self,
+        invocation: ToolInvocation,
+    ) -> std::result::Result<ToolOutput, codewhale_tools::FunctionCallError> {
+        self.started.notify_waiters();
+        self.release.notified().await;
+        Ok(ToolOutput::Function {
+            body: Some(json!({
+                "tool": invocation.tool_name,
+                "call_id": invocation.call_id
+            })),
+            success: true,
+        })
+    }
+}
+
+struct ReentrantHandler {
+    registry: Arc<OnceLock<Arc<ToolRegistry>>>,
+}
+
+#[async_trait]
+impl ToolHandler for ReentrantHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(
+        &self,
+        _invocation: ToolInvocation,
+    ) -> std::result::Result<ToolOutput, codewhale_tools::FunctionCallError> {
+        let registry = self.registry.get().expect("registry initialized").clone();
+        registry
+            .dispatch(
+                ToolCall {
+                    name: "inner".to_string(),
+                    payload: ToolPayload::Function {
+                        arguments: "{}".to_string(),
+                    },
+                    source: ToolCallSource::Direct,
+                    raw_tool_call_id: Some("inner-call".to_string()),
+                },
+                true,
+            )
+            .await
+    }
+}
+
 #[tokio::test]
 async fn dispatches_function_tool_with_parallel_flag() {
     let mut registry = ToolRegistry::default();
@@ -68,3 +128,149 @@ async fn dispatches_function_tool_with_parallel_flag() {
         other => panic!("unexpected output: {other:?}"),
     }
 }
+
+#[tokio::test]
+async fn serial_tool_waits_for_running_parallel_tool() {
+    let started = Arc::new(Notify::new());
+    let release = Arc::new(Notify::new());
+    let mut registry = ToolRegistry::default();
+    registry
+        .register(
+            ToolSpec {
+                name: "slow_read".to_string(),
+                input_schema: json!({"type":"object"}),
+                output_schema: json!({"type":"object"}),
+                supports_parallel_tool_calls: true,
+                timeout_ms: Some(1000),
+            },
+            Arc::new(BlockingHandler {
+                started: started.clone(),
+                release: release.clone(),
+            }),
+        )
+        .expect("register slow read");
+    registry
+        .register(
+            ToolSpec {
+                name: "serial".to_string(),
+                input_schema: json!({"type":"object"}),
+                output_schema: json!({"type":"object"}),
+                supports_parallel_tool_calls: false,
+                timeout_ms: Some(1000),
+            },
+            Arc::new(EchoHandler),
+        )
+        .expect("register serial");
+
+    let registry = Arc::new(registry);
+    let started_wait = started.notified();
+    let parallel_registry = registry.clone();
+    let parallel = tokio::spawn(async move {
+        parallel_registry
+            .dispatch(
+                ToolCall {
+                    name: "slow_read".to_string(),
+                    payload: ToolPayload::Function {
+                        arguments: "{}".to_string(),
+                    },
+                    source: ToolCallSource::Direct,
+                    raw_tool_call_id: Some("parallel-call".to_string()),
+                },
+                true,
+            )
+            .await
+    });
+    tokio::time::timeout(Duration::from_secs(1), started_wait)
+        .await
+        .expect("parallel tool started");
+
+    let serial_registry = registry.clone();
+    let mut serial = tokio::spawn(async move {
+        serial_registry
+            .dispatch(
+                ToolCall {
+                    name: "serial".to_string(),
+                    payload: ToolPayload::Function {
+                        arguments: "{}".to_string(),
+                    },
+                    source: ToolCallSource::Direct,
+                    raw_tool_call_id: Some("serial-call".to_string()),
+                },
+                true,
+            )
+            .await
+    });
+
+    tokio::select! {
+        _ = &mut serial => panic!("serial tool overlapped a running parallel tool"),
+        () = tokio::time::sleep(Duration::from_millis(50)) => {}
+    }
+
+    release.notify_waiters();
+    serial
+        .await
+        .expect("serial task panicked")
+        .expect("serial ran");
+    parallel
+        .await
+        .expect("parallel task panicked")
+        .expect("parallel ran");
+}
+
+#[tokio::test]
+async fn serial_tool_can_reenter_registry_without_deadlock() {
+    let registry_cell = Arc::new(OnceLock::new());
+    let mut registry = ToolRegistry::default();
+    registry
+        .register(
+            ToolSpec {
+                name: "outer".to_string(),
+                input_schema: json!({"type":"object"}),
+                output_schema: json!({"type":"object"}),
+                supports_parallel_tool_calls: false,
+                timeout_ms: Some(1000),
+            },
+            Arc::new(ReentrantHandler {
+                registry: registry_cell.clone(),
+            }),
+        )
+        .expect("register outer");
+    registry
+        .register(
+            ToolSpec {
+                name: "inner".to_string(),
+                input_schema: json!({"type":"object"}),
+                output_schema: json!({"type":"object"}),
+                supports_parallel_tool_calls: false,
+                timeout_ms: Some(1000),
+            },
+            Arc::new(EchoHandler),
+        )
+        .expect("register inner");
+
+    let registry = Arc::new(registry);
+    assert!(registry_cell.set(registry.clone()).is_ok());
+
+    let output = tokio::time::timeout(
+        Duration::from_secs(1),
+        registry.dispatch(
+            ToolCall {
+                name: "outer".to_string(),
+                payload: ToolPayload::Function {
+                    arguments: "{}".to_string(),
+                },
+                source: ToolCallSource::Direct,
+                raw_tool_call_id: Some("outer-call".to_string()),
+            },
+            true,
+        ),
+    )
+    .await
+    .expect("outer dispatch timed out")
+    .expect("outer dispatch failed");
+
+    match output {
+        ToolOutput::Function { success, .. } => assert!(success),
+        other => panic!("unexpected output: {other:?}"),
+    }
+}
diff --git a/crates/tui/CHANGELOG.md b/crates/tui/CHANGELOG.md
index f6fda0e4..924e4f2f 100644
--- a/crates/tui/CHANGELOG.md
+++ b/crates/tui/CHANGELOG.md
@@ -7,6 +7,218 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Composer text selection with copy/cut.** Mouse drag and Shift+Arrow
+  selection in the composer input box, with Ctrl+C copy and Ctrl+X cut
+  support. Home, End, Ctrl+A, and Ctrl+E now clear the selection (#2228).
+- **Copy transcript without visual-wrap newlines.** Transcript copy now
+  strips visual-wrap column line breaks from paragraphs, producing clean
+  text for pasting into editors or prompts (#1906).
+- **Configurable base URL in /config view.** The `/config` panel now
+  displays the effective DeepSeek base URL (#1967).
+- **CNB mirror support for China-friendly downloads.** Added
+  `CODEWHALE_RELEASE_BASE_URL` and `CODEWHALE_USE_CNB_MIRROR` to
+  both npm install scripts and Rust self-updater (#2222).
+- **[✓] completion markers.** Checklist, plan, and tool completion
+  markers now render as `[✓]` instead of `[x]` (#1935).
+
+### Changed
+
+- **Project context loading now logs the source file.** (#2227)
+- **macOS onboarding and empty-state layout pinned to top** instead
+  of vertically centered (#1837).
+- **State-root migration continues.** Migrated 15+ storage paths to
+  prefer `~/.codewhale` with `~/.deepseek` fallback (#2231).
+- **READMEs updated for the CodeWhale rename.** All three READMEs now
+  reference canonical `~/.codewhale` paths.
+
+### Fixed
+
+- **Deadlock when spawning multiple concurrent sub-agents.** Replaced
+  `RwLock`-based serialisation with a `Semaphore(1)` (#1856).
+- **Steered/queued messages now render in correct transcript order.**
+  `steer_user_message` now flushes the active cell before inserting (#2225).
+- **Session save test updated for managed sessions directory.** (#2223).
+- **Loop guard reports Failed on halt.** Turn outcome correctly reports
+  `Failed` instead of `Completed` when the loop guard trips (#1859).
+- **DEEPSEEK_YOLO env honoured on startup.** The `--yolo` flag is now
+  correctly merged with the `DEEPSEEK_YOLO` environment variable (#1870).
+
+### Community
+
+Thanks to contributors whose PRs landed in this release:
+**@Fire-dtx** (#1856),
+**@imkingjh999** (#2228),
+**@harvey2011888** (#1859),
+**@victorcheng2333** (#1870),
+**@IIzzaya** (#1935),
+**@PurplePulse** (#1837),
+**@cyq1017** (#1967),
+**@knqiufan** (#1906).
+
+## [0.8.46] - 2026-05-26
+
+### Added
+
+- **`CODEWHALE_*` env aliases.** `CODEWHALE_PROVIDER`, `CODEWHALE_MODEL`,
+  and `CODEWHALE_BASE_URL` are public product-scoped aliases that take
+  precedence over the legacy `DEEPSEEK_*` forms. The `DEEPSEEK_*` names
+  remain accepted for back-compat.
+- **Platform archive bundles.** Release artifacts now ship as per-platform
+  archives (`tar.gz` for Linux/macOS, `.zip` for Windows) containing both
+  `codewhale` and `codewhale-tui` binaries plus an install script. No more
+  downloading two loose files and guessing which ones to pick (#2193).
+- **Windows portable archive.** `codewhale-windows-x64-portable.zip` ships
+  the two binaries without an install script for USB-stick distribution
+  (#2193).
+- **Web install download tile.** The website install page now shows a
+  platform-aware download tile with arch detection, SHA256 checksum
+  display, and China mirror links, instead of burying the download behind
+  the Cargo instructions (#2192).
+- **Whale dark palette refresh.** Better contrast and layer separation
+  across the TUI color scheme (#2197).
+- **Auto-collapse finished sub-agents.** Completed sub-agent sessions now
+  collapse automatically in the sidebar, reducing noise during long
+  sessions (#2195).
+- **Shell-running status chip.** A `⏳ shell running` chip appears in the
+  TUI footer while background shell tasks are active (#2194).
+- **Sandbox process hardening (Linux).** `PR_SET_DUMPABLE=0`,
+  `NO_NEW_PRIVS`, and `RLIMIT_CORE=0` are applied at shell startup to
+  harden child processes against inspection and privilege escalation
+  (#2183).
+- **CONTRIBUTING.md cross-links.** Issue and PR templates are now
+  cross-linked from CONTRIBUTING.md to improve contributor onboarding
+  (#2203).
+
+### Changed
+
+- **DeepSeek-first focus.** v0.8.46 refocuses on delivering the
+  highest-quality experience on DeepSeek first. Additional first-class
+  provider paths are planned for v0.9.0 after the core DeepSeek workflow
+  is solid.
+
+### Fixed
+
+- **Model name casing preserved.** `normalize_model_name_for_provider` no
+  longer lowercases user-set model names such as `DeepSeek-V4-Flash`,
+  preventing API lookup failures on case-sensitive backends (#2109).
+- **Esc in model picker applies selection.** Dismissing the model picker
+  with Esc now applies the last-highlighted choice instead of reverting
+  (#2196).
+- **Web install downloads both binaries.** The `install-binary.tsx`
+  snippet now fetches both `codewhale` and `codewhale-tui`, fixing the
+  `MISSING_COMPANION_BINARY` trap on fresh npm installs (#2191).
+- **`grep_files` skips large directories.** The pure-Rust search tool
+  now skips known-large directories (`.git`, `node_modules`, `target`)
+  before walking, preventing hangs on deep or slow filesystems.
+- **Version-update hint uses semver.** The update notification in the
+  footer now compares versions semantically instead of lexicographically,
+  so `0.8.10 > 0.8.9` is recognized correctly.
+- **CVE-2026-8723 in feishu-bridge.** Bumped `qs` to `>=6.15.2` in the
+  Feishu bridge integration (#2198).
+
+### Community
+
+Thanks to new contributors whose PRs landed in this release:
+**@donglovejava** (#2154, #2163, #2166, #2167, #2168),
+**@encyc** (#2152),
+**@saieswar237** (#2178),
+**@sximelon** (#2174),
+**@nanookclaw** (#2135),
+**@Sskift** (#2119),
+**@xin1104** (#2105),
+**@mrluanma** (#2059),
+**@Lellansin** (#2055),
+**@zhuangbiaowei** (#2145),
+**@aboimpinto** (#1872),
+and continuing contributors **@reidliu41**, **@cyq1017**, **@idling11**,
+**@h3c-hexin**, **@wdw8276**, **@zlh124**, and **@jeoor**.
+
+## [0.8.45] - 2026-05-25
+
+### Added
+
+- **RLM session objects.** `rlm_open` can now load `session://` refs,
+  exposing the active prompt, history, and session data as symbolic objects
+  inside RLM REPLs (#2047).
+- **Command palette voice input.** The command palette can launch a configured
+  speech-to-text helper and show footer status while transcription runs
+  (#2047).
+- **Moonshot/Kimi provider.** Moonshot/Kimi is now a first-class provider,
+  including API-key auth, model completion, CLI auth, secret-store
+  integration, and optional Kimi CLI credential reuse.
+- **Deterministic whale-species sub-agent names.** Sub-agents now get stable,
+  human-readable whale-species nicknames (e.g. "Beluga", "Orca") while
+  preserving the raw agent ID in the popup (#2035, #2016).
+- **`/balance` command scaffold.** Registered the `/balance` slash command
+  as a placeholder for future provider billing queries (#2035, #2019).
+- **Readable `/restore` snapshot labels.** Snapshot labels now include the
+  originating user prompt so restore listings are easier to identify. Thanks
+  @idling11 (#2111).
+- **Sidebar hover tooltips.** Truncated Work and Tasks sidebar lines now expose
+  their full text on hover. Thanks @idling11 (#2110).
+
+### Changed
+
+- **AGENTS.md is now maintainer-local.** The project instructions file no
+  longer ships as a tracked repo file; it lives in maintainer-local ignored
+  state (#2047).
+
+### Fixed
+
+- **Sub-agent completion handoff compatibility.** Completion handoffs now use a
+  chat-template-safe role and emit before terminal updates, fixing strict
+  OpenAI-compatible/self-hosted backends and preserving transcript ordering.
+  Thanks @h3c-hexin and @cyq1017 (#2057, #2120).
+- **Self-hosted context budgeting.** Sub-500K self-hosted model windows now keep
+  a usable input budget instead of disabling preflight compaction after output
+  reservation underflow. Thanks @h3c-hexin (#2060).
+- **Goal prompts start actionable.** Goal-start prompts now open in an
+  actionable state instead of requiring an extra nudge. Thanks @cyq1017
+  (#2097).
+- **Composer session title display.** The composer chrome shows the current
+  session title again and avoids grayscale luma overflow in debug builds.
+  Thanks @wdw8276 (#2108).
+- **Approval prompts use a one-step confirmation flow.** Enter now commits the
+  selected approval option directly, destructive warnings remain visible, and
+  abort cancels the active turn instead of only denying the current tool call.
+  Thanks @reidliu41 (#2143).
+- **Model picker selection survives Esc.** Dismissing the model picker with Esc
+  no longer loses the highlighted selection. Thanks @reidliu41 (#2056).
+- **Moonshot/Kimi sessions launch from the dispatcher.** The `codewhale`
+  wrapper now includes Moonshot/Kimi in the TUI provider allowlist, so
+  `codewhale --provider moonshot --model kimi-k2.6` reaches the TUI instead of
+  stopping after config resolution.
+- **Slash recovery no longer restores command tails in the composer.**
+  Resuming a session or recovering from a crash no longer leaves stale
+  slash-command text (e.g. `/sessions`) in the composer input (#2047, #2032).
+- **Remembered tool approvals now update the live active turn.**
+  When the "remember" checkbox is set on an approval dialog, the active
+  turn's auto-approve flag flips immediately instead of waiting for the
+  next turn. Thanks @gaord (#2047, #2041).
+- **YAML block scalars in SKILL.md frontmatter.** Multi-line descriptions
+  using `>` or `|` indicators are now parsed correctly — folded block
+  scalars join non-empty lines with spaces, literal scalars preserve
+  newlines, and all three chomping modes (strip/clip/keep) are supported.
+  Thanks @zlh124 (#1908, #1907).
+- **User messages highlighted in the transcript.** User-authored messages
+  now render with a full-row background in the live TUI transcript, making
+  it easier to scan prior turns. Assistant and system messages are
+  unaffected. Thanks @reidliu41 (#1995, #1672).
+- **Cancellable `list_dir` and `file_search`.** Long directory walks and
+  file searches now respond to user cancel/stop requests with a 30-second
+  fallback timeout, preventing the TUI from hanging on deep or slow
+  filesystems (#2035).
+
+### Community
+
+- **README contributor acknowledgements resynced.** The Thanks list now
+  includes the latest contributor rows for @donglovejava, @encyc,
+  @saieswar237, @sximelon, @nanookclaw, @Sskift, @xin1104, @mrluanma,
+  @Lellansin, and @zhuangbiaowei, while preserving the existing @jeoor
+  acknowledgement in the consolidated list.
+
 ## [0.8.44] - 2026-05-24
 
 ### Added
@@ -4806,7 +5018,9 @@ Welcome — and thank you.
 - Hooks system and config profiles
 - Example skills and launch assets
 
-[Unreleased]: https://github.com/Hmbown/CodeWhale/compare/v0.8.44...HEAD
+[Unreleased]: https://github.com/Hmbown/CodeWhale/compare/v0.8.46...HEAD
+[0.8.46]: https://github.com/Hmbown/CodeWhale/compare/v0.8.45...v0.8.46
+[0.8.45]: https://github.com/Hmbown/CodeWhale/compare/v0.8.44...v0.8.45
 [0.8.44]: https://github.com/Hmbown/CodeWhale/compare/v0.8.43...v0.8.44
 [0.8.43]: https://github.com/Hmbown/CodeWhale/compare/v0.8.42...v0.8.43
 [0.8.42]: https://github.com/Hmbown/CodeWhale/compare/v0.8.41...v0.8.42
diff --git a/crates/tui/Cargo.toml b/crates/tui/Cargo.toml
index f78b57a4..67d4042a 100644
--- a/crates/tui/Cargo.toml
+++ b/crates/tui/Cargo.toml
@@ -27,9 +27,10 @@ path = "src/bin/deepseek_tui_legacy_shim.rs"
 [dependencies]
 anyhow = "1.0.100"
 arboard = "3.4"
-codewhale-config = { path = "../config", version = "0.8.44" }
-codewhale-secrets = { path = "../secrets", version = "0.8.44" }
-codewhale-tools = { path = "../tools", version = "0.8.44" }
+codewhale-config = { path = "../config", version = "0.8.46" }
+codewhale-release = { path = "../release", version = "0.8.46" }
+codewhale-secrets = { path = "../secrets", version = "0.8.46" }
+codewhale-tools = { path = "../tools", version = "0.8.46" }
 schemaui = { version = "0.12.0", default-features = false, optional = true }
 async-stream = "0.3.6"
 async-trait = "0.1"
@@ -45,7 +46,7 @@ fd-lock = "4.0.4"
 futures-util = "0.3.31"
 ratatui = "0.30"
 regex = "1.11"
-reqwest = { version = "0.13.1", default-features = false, features = ["blocking", "json", "stream", "multipart", "rustls", "http2", "gzip", "brotli"] }
+reqwest = { version = "0.13.1", default-features = false, features = ["blocking", "json", "stream", "multipart", "form", "rustls", "http2", "gzip", "brotli"] }
 similar = "2"
 rustyline = "15.0.0"
 serde = { version = "1.0.228", features = ["derive"] }
@@ -70,7 +71,7 @@ multimap = "0.10.0"
 shlex = "1.3.0"
 starlark = "0.13.0"
 tiny_http = "0.12"
-portable-pty = "0.8"
+portable-pty = "0.9"
 zeroize = "1.8.2"
 ignore = "0.4"
 image = { version = "0.25", default-features = false, features = ["png"] }
diff --git a/crates/tui/src/audit.rs b/crates/tui/src/audit.rs
index 60b49c63..2638131d 100644
--- a/crates/tui/src/audit.rs
+++ b/crates/tui/src/audit.rs
@@ -41,5 +41,5 @@ fn append_event(event: &str, details: Value) -> anyhow::Result<()> {
 
 fn default_audit_path() -> anyhow::Result<PathBuf> {
     let home = dirs::home_dir().ok_or_else(|| anyhow::anyhow!("home directory not found"))?;
-    Ok(home.join(".deepseek").join("audit.log"))
+    Ok(home.join(".codewhale").join("audit.log"))
 }
diff --git a/crates/tui/src/automation_manager.rs b/crates/tui/src/automation_manager.rs
index c98dc7e8..79bc8765 100644
--- a/crates/tui/src/automation_manager.rs
+++ b/crates/tui/src/automation_manager.rs
@@ -795,8 +795,15 @@ pub fn default_automations_dir() -> PathBuf {
         }
     }
     dirs::home_dir()
-        .map(|home| home.join(".deepseek").join("automations"))
-        .unwrap_or_else(|| PathBuf::from(".deepseek").join("automations"))
+        .map(|home| {
+            let primary = home.join(".codewhale").join("automations");
+            if primary.exists() {
+                primary
+            } else {
+                home.join(".deepseek").join("automations")
+            }
+        })
+        .unwrap_or_else(|| PathBuf::from(".codewhale").join("automations"))
 }
 
 pub type SharedAutomationManager = Arc<Mutex<AutomationManager>>;
diff --git a/crates/tui/src/client.rs b/crates/tui/src/client.rs
index 8ecd3e4c..15e5778f 100644
--- a/crates/tui/src/client.rs
+++ b/crates/tui/src/client.rs
@@ -882,8 +882,10 @@ pub(super) fn apply_reasoning_effort(
             ApiProvider::Deepseek
             | ApiProvider::DeepseekCN
             | ApiProvider::Openrouter
+            | ApiProvider::XiaomiMimo
             | ApiProvider::Novita
-            | ApiProvider::Sglang => {
+            | ApiProvider::Sglang
+            | ApiProvider::Volcengine => {
                 body["thinking"] = json!({ "type": "disabled" });
             }
             ApiProvider::Fireworks => {}
@@ -904,6 +906,7 @@ pub(super) fn apply_reasoning_effort(
             ApiProvider::Openai
             | ApiProvider::Atlascloud
             | ApiProvider::WanjieArk
+            | ApiProvider::Moonshot
             | ApiProvider::Ollama => {}
             ApiProvider::NvidiaNim => {
                 body["chat_template_kwargs"] = json!({
@@ -913,7 +916,10 @@ pub(super) fn apply_reasoning_effort(
         },
         "low" | "minimal" | "medium" | "mid" | "high" | "" => match provider {
             // DeepSeek compatibility: low/medium both map to high
-            ApiProvider::Deepseek | ApiProvider::DeepseekCN | ApiProvider::Sglang => {
+            ApiProvider::Deepseek
+            | ApiProvider::DeepseekCN
+            | ApiProvider::Sglang
+            | ApiProvider::Volcengine => {
                 body["reasoning_effort"] = json!("high");
                 body["thinking"] = json!({ "type": "enabled" });
             }
@@ -929,6 +935,9 @@ pub(super) fn apply_reasoning_effort(
                 body["reasoning_effort"] = json!(value);
                 body["thinking"] = json!({ "type": "enabled" });
             }
+            ApiProvider::XiaomiMimo => {
+                body["thinking"] = json!({ "type": "enabled" });
+            }
             ApiProvider::Fireworks => {
                 body["reasoning_effort"] = json!("high");
             }
@@ -936,11 +945,19 @@ pub(super) fn apply_reasoning_effort(
                 body["chat_template_kwargs"] = json!({
                     "enable_thinking": true,
                 });
-                body["reasoning_effort"] = json!("high");
+                // vLLM supports low/medium/high natively — pass through the
+                // user-chosen value instead of hard-coding "high".
+                let value = match normalized.as_str() {
+                    "low" | "minimal" => "low",
+                    "medium" | "mid" => "medium",
+                    _ => "high",
+                };
+                body["reasoning_effort"] = json!(value);
             }
             ApiProvider::Openai
             | ApiProvider::Atlascloud
             | ApiProvider::WanjieArk
+            | ApiProvider::Moonshot
             | ApiProvider::Ollama => {}
             ApiProvider::NvidiaNim => {
                 body["chat_template_kwargs"] = json!({
@@ -950,7 +967,10 @@ pub(super) fn apply_reasoning_effort(
             }
         },
         "xhigh" | "max" | "highest" => match provider {
-            ApiProvider::Deepseek | ApiProvider::DeepseekCN | ApiProvider::Sglang => {
+            ApiProvider::Deepseek
+            | ApiProvider::DeepseekCN
+            | ApiProvider::Sglang
+            | ApiProvider::Volcengine => {
                 body["reasoning_effort"] = json!("max");
                 body["thinking"] = json!({ "type": "enabled" });
             }
@@ -958,6 +978,9 @@ pub(super) fn apply_reasoning_effort(
                 body["reasoning_effort"] = json!("xhigh");
                 body["thinking"] = json!({ "type": "enabled" });
             }
+            ApiProvider::XiaomiMimo => {
+                body["thinking"] = json!({ "type": "enabled" });
+            }
             ApiProvider::Fireworks => {
                 body["reasoning_effort"] = json!("max");
             }
@@ -965,11 +988,14 @@ pub(super) fn apply_reasoning_effort(
                 body["chat_template_kwargs"] = json!({
                     "enable_thinking": true,
                 });
-                body["reasoning_effort"] = json!("max");
+                // vLLM only supports none/low/medium/high — downgrade
+                // "max" to "high" instead of sending an invalid value.
+                body["reasoning_effort"] = json!("high");
             }
             ApiProvider::Openai
             | ApiProvider::Atlascloud
             | ApiProvider::WanjieArk
+            | ApiProvider::Moonshot
             | ApiProvider::Ollama => {}
             ApiProvider::NvidiaNim => {
                 body["chat_template_kwargs"] = json!({
@@ -1113,6 +1139,23 @@ mod tests {
     };
     use serde_json::json;
 
+    fn test_tool(name: &str) -> Tool {
+        Tool {
+            tool_type: None,
+            name: name.to_string(),
+            description: format!("{name} test tool"),
+            input_schema: json!({
+                "type": "object",
+                "properties": {},
+            }),
+            allowed_callers: None,
+            defer_loading: Some(false),
+            input_examples: None,
+            strict: Some(true),
+            cache_control: None,
+        }
+    }
+
     #[test]
     fn tool_name_roundtrip_dot() {
         let original = "multi_tool_use.parallel";
@@ -1286,7 +1329,7 @@ mod tests {
         // and DOES replay reasoning_content — see
         // `deepseek_model_on_openai_provider_still_replays_reasoning_content`.
         let request = MessageRequest {
-            model: "gpt-4o".to_string(),
+            model: "qwen3-coder".to_string(),
             messages: vec![Message {
                 role: "assistant".to_string(),
                 content: vec![
@@ -1798,6 +1841,49 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn prompt_inspect_tracks_tool_catalog_in_static_prefix_hash() {
+        let request = MessageRequest {
+            model: "deepseek-v4-pro".to_string(),
+            messages: vec![Message {
+                role: "user".to_string(),
+                content: vec![ContentBlock::Text {
+                    text: "Current task".to_string(),
+                    cache_control: None,
+                }],
+            }],
+            max_tokens: 1024,
+            system: Some(SystemPrompt::Text("Base policy".to_string())),
+            tools: Some(vec![test_tool("read_file")]),
+            tool_choice: None,
+            metadata: None,
+            thinking: None,
+            reasoning_effort: Some("max".to_string()),
+            stream: None,
+            temperature: None,
+            top_p: None,
+        };
+
+        let first = inspect_prompt_for_request(&request);
+        let mut changed_tools = request.clone();
+        changed_tools.tools = Some(vec![test_tool("read_file"), test_tool("grep_files")]);
+        let second = inspect_prompt_for_request(&changed_tools);
+
+        assert!(
+            first.layers.iter().any(|layer| {
+                layer.name == "Tool catalog" && layer.stability.label() == "static"
+            })
+        );
+        assert_ne!(
+            first.base_static_prefix_hash, second.base_static_prefix_hash,
+            "tool schema changes must be visible to cache-inspect base prefix diagnostics"
+        );
+        assert_ne!(
+            first.full_request_prefix_hash, second.full_request_prefix_hash,
+            "tool schema changes must be visible to full reusable-prefix diagnostics"
+        );
+    }
+
     #[test]
     fn cache_warmup_request_reuses_stable_prefix_and_fixed_user_tail() {
         let request = MessageRequest {
@@ -1823,7 +1909,7 @@ mod tests {
                 "Base policy\n\n<project_instructions source=\"AGENTS.md\">\nStable project rules\n</project_instructions>\n\n## Previous Session Relay\n\nDynamic relay"
                     .to_string(),
             )),
-            tools: None,
+            tools: Some(vec![test_tool("read_file")]),
             tool_choice: None,
             metadata: None,
             thinking: None,
@@ -1838,6 +1924,8 @@ mod tests {
         assert_eq!(warmup.max_tokens, 8);
         assert_eq!(warmup.temperature, Some(0.0));
         assert_eq!(warmup.reasoning_effort.as_deref(), Some("max"));
+        assert_eq!(warmup.tools.as_ref().map(Vec::len), Some(1));
+        assert_eq!(warmup.tool_choice, Some(json!("none")));
         assert_eq!(warmup.messages.len(), 2);
         assert_eq!(warmup.messages[0].role, "assistant");
         assert_eq!(warmup.messages[1].role, "user");
@@ -1970,6 +2058,29 @@ mod tests {
         }
     }
 
+    #[test]
+    fn reasoning_effort_uses_xiaomi_mimo_thinking_parameter_only() {
+        for input in ["low", "medium", "max", "xhigh"] {
+            let mut body = json!({});
+            apply_reasoning_effort(&mut body, Some(input), ApiProvider::XiaomiMimo);
+
+            assert_eq!(
+                body.pointer("/thinking/type").and_then(Value::as_str),
+                Some("enabled"),
+                "MiMo thinking mapping for {input}"
+            );
+            assert!(body.get("reasoning_effort").is_none());
+        }
+
+        let mut body = json!({});
+        apply_reasoning_effort(&mut body, Some("off"), ApiProvider::XiaomiMimo);
+        assert_eq!(
+            body.pointer("/thinking/type").and_then(Value::as_str),
+            Some("disabled")
+        );
+        assert!(body.get("reasoning_effort").is_none());
+    }
+
     #[test]
     fn chat_parser_accepts_nvidia_nim_reasoning_field() -> Result<()> {
         let response = parse_chat_message(&json!({
@@ -2745,7 +2856,7 @@ mod tests {
         // DeepSeek reasoning model on the openai provider still gets sanitized
         // (see chat.rs `deepseek_model_on_openai_provider_still_replays_*`).
         let mut body = json!({
-            "model": "gpt-4o",
+            "model": "qwen3-coder",
             "messages": [
                 { "role": "user", "content": "hi" },
                 {
@@ -2756,8 +2867,12 @@ mod tests {
             ]
         });
 
-        let result =
-            sanitize_thinking_mode_messages(&mut body, "gpt-4o", Some("max"), ApiProvider::Openai);
+        let result = sanitize_thinking_mode_messages(
+            &mut body,
+            "qwen3-coder",
+            Some("max"),
+            ApiProvider::Openai,
+        );
 
         assert!(result.is_none());
         let assistant = body["messages"]
@@ -2846,6 +2961,10 @@ mod tests {
 
     #[test]
     fn base_url_security_rejects_insecure_non_local_http() {
+        let _lock = ALLOW_INSECURE_HTTP_ENV_LOCK.lock().unwrap();
+        let _guard = AllowInsecureHttpEnvGuard::capture();
+        unsafe { std::env::remove_var(ALLOW_INSECURE_HTTP_ENV) };
+
         let err = validate_base_url_security("http://api.deepseek.com")
             .expect_err("non-local insecure HTTP should be rejected");
         assert!(err.to_string().contains("Refusing insecure base URL"));
@@ -2853,10 +2972,46 @@ mod tests {
 
     #[test]
     fn base_url_security_allows_localhost_http() {
+        let _lock = ALLOW_INSECURE_HTTP_ENV_LOCK.lock().unwrap();
+        let _guard = AllowInsecureHttpEnvGuard::capture();
+        unsafe { std::env::remove_var(ALLOW_INSECURE_HTTP_ENV) };
+
         assert!(validate_base_url_security("http://localhost:8080").is_ok());
         assert!(validate_base_url_security("http://127.0.0.1:8080").is_ok());
     }
 
+    #[test]
+    fn base_url_security_allows_non_local_http_with_explicit_opt_in() {
+        let _lock = ALLOW_INSECURE_HTTP_ENV_LOCK.lock().unwrap();
+        let _guard = AllowInsecureHttpEnvGuard::capture();
+        unsafe { std::env::set_var(ALLOW_INSECURE_HTTP_ENV, "1") };
+
+        assert!(validate_base_url_security("http://192.168.0.110:8000/v1").is_ok());
+    }
+
+    /// Serialize tests that mutate `DEEPSEEK_ALLOW_INSECURE_HTTP`; env vars are
+    /// process-global and would otherwise leak across security checks.
+    static ALLOW_INSECURE_HTTP_ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+    struct AllowInsecureHttpEnvGuard {
+        prior: Option<std::ffi::OsString>,
+    }
+    impl AllowInsecureHttpEnvGuard {
+        fn capture() -> Self {
+            Self {
+                prior: std::env::var_os(ALLOW_INSECURE_HTTP_ENV),
+            }
+        }
+    }
+    impl Drop for AllowInsecureHttpEnvGuard {
+        fn drop(&mut self) {
+            match &self.prior {
+                Some(v) => unsafe { std::env::set_var(ALLOW_INSECURE_HTTP_ENV, v) },
+                None => unsafe { std::env::remove_var(ALLOW_INSECURE_HTTP_ENV) },
+            }
+        }
+    }
+
     #[test]
     fn connection_health_degrades_and_recovers() {
         let now = Instant::now();
diff --git a/crates/tui/src/client/chat.rs b/crates/tui/src/client/chat.rs
index 1b691110..1c66079a 100644
--- a/crates/tui/src/client/chat.rs
+++ b/crates/tui/src/client/chat.rs
@@ -71,6 +71,17 @@ use super::{
     release_stream_buffer, system_to_instructions, to_api_tool_name,
 };
 
+fn apply_provider_token_limit(body: &mut Value, provider: ApiProvider, max_tokens: u32) {
+    if provider != ApiProvider::XiaomiMimo {
+        return;
+    }
+
+    if let Some(object) = body.as_object_mut() {
+        object.remove("max_tokens");
+    }
+    body["max_completion_tokens"] = json!(max_tokens);
+}
+
 impl DeepSeekClient {
     pub(super) async fn create_message_chat(
         &self,
@@ -82,6 +93,7 @@ impl DeepSeekClient {
             "messages": messages,
             "max_tokens": request.max_tokens,
         });
+        apply_provider_token_limit(&mut body, self.api_provider, request.max_tokens);
 
         if let Some(temperature) = request.temperature {
             body["temperature"] = json!(temperature);
@@ -156,6 +168,7 @@ impl DeepSeekClient {
                 "include_usage": true
             },
         });
+        apply_provider_token_limit(&mut body, self.api_provider, request.max_tokens);
 
         if let Some(temperature) = request.temperature {
             body["temperature"] = json!(temperature);
@@ -438,6 +451,7 @@ pub(crate) fn build_cache_warmup_request(request: &MessageRequest) -> MessageReq
 struct PromptBuilder<'a> {
     system: Option<&'a SystemPrompt>,
     messages: &'a [Message],
+    tools: Option<&'a [Tool]>,
     model: &'a str,
     reasoning_effort: Option<&'a str>,
 }
@@ -447,6 +461,7 @@ impl<'a> PromptBuilder<'a> {
         Self {
             system: request.system.as_ref(),
             messages: &request.messages,
+            tools: request.tools.as_deref(),
             model: &request.model,
             reasoning_effort: request.reasoning_effort.as_deref(),
         }
@@ -485,12 +500,17 @@ impl<'a> PromptBuilder<'a> {
             should_replay_reasoning_content(self.model, self.reasoning_effort),
             true,
         );
-        inspect_wire_messages(&messages)
+        inspect_wire_request(self.tools, &messages)
     }
 
     fn build_cache_warmup_request(self) -> MessageRequest {
         let system = stable_system_prompt(self.system);
         let mut messages = stable_history_messages(self.messages);
+        let tools = self
+            .tools
+            .filter(|tools| !tools.is_empty())
+            .map(<[Tool]>::to_vec);
+        let tool_choice = tools.as_ref().map(|_| json!("none"));
         messages.push(Message {
             role: "user".to_string(),
             content: vec![ContentBlock::Text {
@@ -504,8 +524,8 @@ impl<'a> PromptBuilder<'a> {
             messages,
             max_tokens: 8,
             system,
-            tools: None,
-            tool_choice: None,
+            tools,
+            tool_choice,
             metadata: None,
             thinking: None,
             reasoning_effort: self.reasoning_effort.map(str::to_string),
@@ -581,20 +601,19 @@ impl PromptLayerStability {
     }
 }
 
-fn inspect_wire_messages(messages: &[Value]) -> PromptInspection {
+fn inspect_wire_request(tools: Option<&[Tool]>, messages: &[Value]) -> PromptInspection {
     let mut layers = Vec::new();
     let mut base_static_prefix_parts = Vec::new();
     let mut full_request_prefix_parts = Vec::new();
+    let mut start_index = 0;
 
-    for (index, message) in messages.iter().enumerate() {
+    if let Some(message) = messages.first() {
         let role = message
             .get("role")
             .and_then(Value::as_str)
             .unwrap_or("unknown");
         let content = message_content_for_inspect(message);
-        let is_last = index + 1 == messages.len();
-
-        if index == 0 && role == "system" {
+        if role == "system" {
             for (name, stability, body) in split_system_layers(&content) {
                 if stability == PromptLayerStability::Static {
                     base_static_prefix_parts.push(body.to_string());
@@ -604,27 +623,46 @@ fn inspect_wire_messages(messages: &[Value]) -> PromptInspection {
                 }
                 layers.push(prompt_layer(name, stability, body));
             }
-        } else {
-            let stability = if (is_last && role == "user") || role == "tool" {
-                PromptLayerStability::Dynamic
-            } else {
-                PromptLayerStability::History
-            };
-            let name = if is_last && role == "user" {
-                "User task".to_string()
-            } else {
-                format!("Message #{index} {role}")
-            };
-            if stability != PromptLayerStability::Dynamic {
-                full_request_prefix_parts.push(content.clone());
-            }
-            let mut layer = prompt_layer(name, stability, &content);
-            layer.tool_result = tool_result_inspection_for_message(message);
-            layer.turn_meta = turn_meta_inspection_for_message(message);
-            layers.push(layer);
+            start_index = 1;
         }
     }
 
+    if let Some(tool_catalog) = tool_catalog_for_inspect(tools) {
+        base_static_prefix_parts.push(tool_catalog.clone());
+        full_request_prefix_parts.push(tool_catalog.clone());
+        layers.push(prompt_layer(
+            "Tool catalog".to_string(),
+            PromptLayerStability::Static,
+            &tool_catalog,
+        ));
+    }
+
+    for (index, message) in messages.iter().enumerate().skip(start_index) {
+        let role = message
+            .get("role")
+            .and_then(Value::as_str)
+            .unwrap_or("unknown");
+        let content = message_content_for_inspect(message);
+        let is_last = index + 1 == messages.len();
+        let stability = if (is_last && role == "user") || role == "tool" {
+            PromptLayerStability::Dynamic
+        } else {
+            PromptLayerStability::History
+        };
+        let name = if is_last && role == "user" {
+            "User task".to_string()
+        } else {
+            format!("Message #{index} {role}")
+        };
+        if stability != PromptLayerStability::Dynamic {
+            full_request_prefix_parts.push(content.clone());
+        }
+        let mut layer = prompt_layer(name, stability, &content);
+        layer.tool_result = tool_result_inspection_for_message(message);
+        layer.turn_meta = turn_meta_inspection_for_message(message);
+        layers.push(layer);
+    }
+
     let base_static_prefix = base_static_prefix_parts.join("\n");
     let full_request_prefix = full_request_prefix_parts.join("\n");
 
@@ -635,6 +673,11 @@ fn inspect_wire_messages(messages: &[Value]) -> PromptInspection {
     }
 }
 
+fn tool_catalog_for_inspect(tools: Option<&[Tool]>) -> Option<String> {
+    let tools = tools.filter(|tools| !tools.is_empty())?;
+    serde_json::to_string(&tools.iter().map(tool_to_chat).collect::<Vec<_>>()).ok()
+}
+
 fn message_content_for_inspect(message: &Value) -> String {
     let mut parts = Vec::new();
     if let Some(content) = message.get("content").and_then(Value::as_str)
@@ -1699,6 +1742,7 @@ fn provider_accepts_reasoning_content(provider: ApiProvider) -> bool {
             | ApiProvider::DeepseekCN
             | ApiProvider::NvidiaNim
             | ApiProvider::Openrouter
+            | ApiProvider::XiaomiMimo
             | ApiProvider::Novita
             | ApiProvider::Fireworks
             | ApiProvider::Sglang
@@ -3062,11 +3106,12 @@ mod alias_thinking_detection_tests {
     //! turn. See upstream API docs:
     //! https://api-docs.deepseek.com/guides/thinking_mode
     use super::{
-        is_reasoning_model_for_stream, provider_accepts_reasoning_content,
-        requires_reasoning_content, should_replay_reasoning_content,
-        should_replay_reasoning_content_for_provider,
+        apply_provider_token_limit, is_reasoning_model_for_stream,
+        provider_accepts_reasoning_content, requires_reasoning_content,
+        should_replay_reasoning_content, should_replay_reasoning_content_for_provider,
     };
     use crate::config::ApiProvider;
+    use serde_json::json;
 
     #[test]
     fn aliases_routed_to_v4_require_reasoning_content() {
@@ -3093,7 +3138,7 @@ mod alias_thinking_detection_tests {
         // `reasoning_content` on providers that reject the field.
         assert!(!requires_reasoning_content("deepseek-v3"));
         assert!(!requires_reasoning_content("deepseek-coder"));
-        assert!(!requires_reasoning_content("gpt-4o"));
+        assert!(!requires_reasoning_content("qwen3-coder"));
         assert!(!requires_reasoning_content("claude-sonnet-4-6"));
     }
 
@@ -3132,6 +3177,25 @@ mod alias_thinking_detection_tests {
         assert!(!provider_accepts_reasoning_content(ApiProvider::Openai));
         assert!(provider_accepts_reasoning_content(ApiProvider::Deepseek));
         assert!(provider_accepts_reasoning_content(ApiProvider::NvidiaNim));
+        assert!(provider_accepts_reasoning_content(ApiProvider::XiaomiMimo));
+    }
+
+    #[test]
+    fn xiaomi_mimo_uses_max_completion_tokens_payload_key() {
+        let mut body = json!({
+            "model": "mimo-v2.5-pro",
+            "messages": [],
+            "max_tokens": 8192,
+        });
+
+        apply_provider_token_limit(&mut body, ApiProvider::XiaomiMimo, 8192);
+
+        assert!(body.get("max_tokens").is_none());
+        assert_eq!(
+            body.get("max_completion_tokens")
+                .and_then(serde_json::Value::as_u64),
+            Some(8192)
+        );
     }
 
     #[test]
@@ -3169,7 +3233,7 @@ mod alias_thinking_detection_tests {
         // openai provider must continue to have reasoning_content stripped.
         assert!(!should_replay_reasoning_content_for_provider(
             ApiProvider::Openai,
-            "gpt-4o",
+            "qwen3-coder",
             None,
         ));
         assert!(!should_replay_reasoning_content_for_provider(
@@ -3211,7 +3275,7 @@ mod alias_thinking_detection_tests {
         // parser keeps inlining any `reasoning_content` it emits as text.
         assert!(!is_reasoning_model_for_stream(
             ApiProvider::Openai,
-            "gpt-4o"
+            "qwen3-coder"
         ));
         assert!(!is_reasoning_model_for_stream(
             ApiProvider::Openai,
@@ -3220,7 +3284,7 @@ mod alias_thinking_detection_tests {
         // Non-DeepSeek model on a reasoning-aware provider is also unchanged.
         assert!(!is_reasoning_model_for_stream(
             ApiProvider::Deepseek,
-            "gpt-4o"
+            "qwen3-coder"
         ));
     }
 
@@ -3230,7 +3294,7 @@ mod alias_thinking_detection_tests {
         // model identity, or stream parsing and message sanitisation disagree
         // about where reasoning tokens live. Effort=None isolates the
         // model/provider dimension shared by both.
-        for model in ["deepseek-v4-pro", "deepseek-reasoner", "gpt-4o"] {
+        for model in ["deepseek-v4-pro", "deepseek-reasoner", "qwen3-coder"] {
             for provider in [ApiProvider::Openai, ApiProvider::Deepseek] {
                 assert_eq!(
                     is_reasoning_model_for_stream(provider, model),
diff --git a/crates/tui/src/commands/anchor.rs b/crates/tui/src/commands/anchor.rs
index fb15fb33..7ba66d7a 100644
--- a/crates/tui/src/commands/anchor.rs
+++ b/crates/tui/src/commands/anchor.rs
@@ -47,6 +47,10 @@ pub fn anchor(app: &mut App, content: Option<&str>) -> CommandResult {
 }
 
 fn anchors_path(app: &App) -> std::path::PathBuf {
+    let primary = app.workspace.join(".codewhale").join("anchors.md");
+    if primary.exists() {
+        return primary;
+    }
     app.workspace.join(".deepseek").join("anchors.md")
 }
 
diff --git a/crates/tui/src/commands/change.rs b/crates/tui/src/commands/change.rs
index e8448a48..e424ec9b 100644
--- a/crates/tui/src/commands/change.rs
+++ b/crates/tui/src/commands/change.rs
@@ -101,6 +101,7 @@ pub fn change(app: &mut App, version: Option<&str>) -> CommandResult {
             Locale::Ja => "Japanese (日本語)",
             Locale::PtBr => "Brazilian Portuguese (Português)",
             Locale::Es419 => "Latin American Spanish (Español latinoamericano)",
+            Locale::Vi => "Vietnamese (Tiếng Việt)",
             // Fallback — should never reach here since we check En above.
             Locale::En => "English",
         };
diff --git a/crates/tui/src/commands/config.rs b/crates/tui/src/commands/config.rs
index 40ffe1dc..c582c7d4 100644
--- a/crates/tui/src/commands/config.rs
+++ b/crates/tui/src/commands/config.rs
@@ -5,7 +5,9 @@ use std::time::Duration;
 
 use super::CommandResult;
 use crate::client::DeepSeekClient;
-use crate::config::{COMMON_DEEPSEEK_MODELS, clear_api_key, normalize_model_name_for_provider};
+use crate::config::{
+    COMMON_DEEPSEEK_MODELS, Config, clear_api_key, expand_path, normalize_model_name_for_provider,
+};
 use crate::config_ui::{ConfigUiMode, parse_mode};
 use crate::llm_client::LlmClient;
 use crate::localization::resolve_locale;
@@ -91,6 +93,7 @@ fn show_single_setting(app: &App, key: &str) -> CommandResult {
             crate::localization::Locale::Ja => "ja",
             crate::localization::Locale::PtBr => "pt-BR",
             crate::localization::Locale::Es419 => "es-419",
+            crate::localization::Locale::Vi => "vi",
         }
     }
     fn density_display(d: crate::tui::app::ComposerDensity) -> &'static str {
@@ -122,6 +125,16 @@ fn show_single_setting(app: &App, key: &str) -> CommandResult {
             }
         }
         "approval_mode" | "approval" => Some(app.approval_mode.label().to_string()),
+        "base_url" => {
+            let config = match Config::load(app.config_path.clone(), app.config_profile.as_deref())
+            {
+                Ok(config) => config,
+                Err(err) => {
+                    return CommandResult::error(format!("Failed to load config: {err}"));
+                }
+            };
+            Some(config.deepseek_base_url())
+        }
         "locale" | "language" => Some(locale_display(app.ui_locale).to_string()),
         "theme" | "ui_theme" => {
             Some(crate::palette::theme_label_for_mode(app.ui_theme.mode).to_string())
@@ -284,7 +297,7 @@ pub fn persist_status_items(items: &[crate::config::StatusItem]) -> anyhow::Resu
     use anyhow::Context;
     use std::fs;
 
-    let path = config_toml_path()?;
+    let path = config_toml_path(None)?;
     if let Some(parent) = path.parent() {
         fs::create_dir_all(parent)
             .with_context(|| format!("failed to create config directory {}", parent.display()))?;
@@ -320,11 +333,15 @@ pub fn persist_status_items(items: &[crate::config::StatusItem]) -> anyhow::Resu
     Ok(path)
 }
 
-pub fn persist_root_string_key(key: &str, value: &str) -> anyhow::Result<PathBuf> {
+pub fn persist_root_string_key(
+    config_path: Option<&Path>,
+    key: &str,
+    value: &str,
+) -> anyhow::Result<PathBuf> {
     use anyhow::Context;
     use std::fs;
 
-    let path = config_toml_path()?;
+    let path = config_toml_path(config_path)?;
     if let Some(parent) = path.parent() {
         fs::create_dir_all(parent)
             .with_context(|| format!("failed to create config directory {}", parent.display()))?;
@@ -351,8 +368,11 @@ pub fn persist_root_string_key(key: &str, value: &str) -> anyhow::Result<PathBuf
 /// Resolve the path to `~/.deepseek/config.toml` (or
 /// `$DEEPSEEK_CONFIG_PATH`). Mirrors what `Config::load` accepts so we
 /// never write to a different file than the one we read.
-pub(super) fn config_toml_path() -> anyhow::Result<PathBuf> {
+pub(super) fn config_toml_path(config_path: Option<&Path>) -> anyhow::Result<PathBuf> {
     use anyhow::Context;
+    if let Some(path) = config_path {
+        return Ok(expand_path(path.to_string_lossy().as_ref()));
+    }
     if let Ok(env) = std::env::var("DEEPSEEK_CONFIG_PATH") {
         let trimmed = env.trim();
         if !trimmed.is_empty() {
@@ -360,6 +380,10 @@ pub(super) fn config_toml_path() -> anyhow::Result<PathBuf> {
         }
     }
     let home = dirs::home_dir().context("failed to resolve home directory for config.toml path")?;
+    let primary = home.join(".codewhale").join("config.toml");
+    if primary.exists() {
+        return Ok(primary);
+    }
     Ok(home.join(".deepseek").join("config.toml"))
 }
 
@@ -417,7 +441,8 @@ pub fn set_config_value(app: &mut App, key: &str, value: &str, persist: bool) ->
             app.mcp_config_path = PathBuf::from(expand_tilde(value));
             app.mcp_restart_required = true;
             let message = if persist {
-                match persist_root_string_key("mcp_config_path", value) {
+                match persist_root_string_key(app.config_path.as_deref(), "mcp_config_path", value)
+                {
                     Ok(path) => format!(
                         "mcp_config_path = {} (saved to {}; restart required for MCP tool pool)",
                         app.mcp_config_path.display(),
@@ -433,6 +458,26 @@ pub fn set_config_value(app: &mut App, key: &str, value: &str, persist: bool) ->
             };
             return CommandResult::message(message);
         }
+        "base_url" => {
+            let value = value.trim();
+            if value.is_empty() {
+                return CommandResult::error("base_url cannot be empty");
+            }
+            if persist {
+                match persist_root_string_key(app.config_path.as_deref(), "base_url", value) {
+                    Ok(path) => {
+                        return CommandResult::message(format!(
+                            "base_url = {value} (saved to {})",
+                            path.display()
+                        ));
+                    }
+                    Err(err) => return CommandResult::error(format!("Failed to save: {err}")),
+                }
+            }
+            return CommandResult::error(
+                "base_url must be saved with --save; client base URL is loaded from config on startup. Restart and re-open your session after saving.",
+            );
+        }
         _ => {}
     }
 
@@ -699,6 +744,47 @@ pub fn theme(app: &mut App, arg: Option<&str>) -> CommandResult {
     }
 }
 
+/// `/slop [query|export]` — inspect or export the slop ledger (#2127).
+/// With no arguments, prints a summary. `query` shows filtered results;
+/// `export` outputs the full ledger as Markdown.
+pub fn slop(_app: &mut App, arg: Option<&str>) -> CommandResult {
+    let arg = arg.map(str::trim).unwrap_or("");
+    let ledger = match crate::slop_ledger::SlopLedger::load() {
+        Ok(l) => l,
+        Err(e) => return CommandResult::error(format!("Failed to load slop ledger: {e}")),
+    };
+
+    match arg {
+        "" => CommandResult::message(ledger.summary()),
+        "query" | "q" => {
+            if ledger.is_empty() {
+                return CommandResult::message("Slop ledger is empty.");
+            }
+            let mut out = String::new();
+            for entry in &ledger.query(&Default::default()) {
+                use std::fmt::Write;
+                let _ = writeln!(
+                    out,
+                    "[{}] {} ({:?} | {:?}) — {}",
+                    crate::slop_ledger::short_id(&entry.id),
+                    entry.bucket.as_str(),
+                    entry.severity,
+                    entry.status,
+                    entry.title
+                );
+            }
+            CommandResult::message(out)
+        }
+        "export" | "e" => {
+            let md = ledger.export_markdown(None, None);
+            CommandResult::message(md)
+        }
+        _ => CommandResult::error(format!(
+            "Unknown /slop action '{arg}'. Use /slop, /slop query, or /slop export."
+        )),
+    }
+}
+
 /// Manage workspace-level trust and the per-path allowlist.
 ///
 /// Subcommands:
@@ -1750,6 +1836,134 @@ mod tests {
         assert!(saved.contains("cost_currency = \"cny\""));
     }
 
+    #[test]
+    fn config_command_base_url_save_persists_value() {
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "deepseek-tui-base-url-test-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root).unwrap();
+        let _guard = EnvGuard::new(&temp_root);
+
+        let mut app = create_test_app();
+        let result = config_command(
+            &mut app,
+            Some("base_url https://example.internal.local/v1 --save"),
+        );
+        let msg = result.message.unwrap();
+        let saved_path = config_toml_path(None).unwrap();
+        let saved = fs::read_to_string(&saved_path).unwrap();
+
+        assert_eq!(
+            msg,
+            format!(
+                "base_url = https://example.internal.local/v1 (saved to {})",
+                saved_path.display()
+            )
+        );
+        assert!(saved.contains("base_url = \"https://example.internal.local/v1\""));
+    }
+
+    #[test]
+    fn config_command_base_url_without_save_requires_save() {
+        let _lock = lock_test_env();
+        let mut app = create_test_app();
+        let result = config_command(&mut app, Some("base_url https://example.internal.local/v1"));
+        assert!(result.is_error);
+        let msg = result.message.unwrap();
+
+        assert!(
+            msg.contains("base_url must be saved with --save"),
+            "got {msg}"
+        );
+    }
+
+    #[test]
+    fn config_command_base_url_reads_current_value_from_config() {
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "deepseek-tui-base-url-show-test-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root).unwrap();
+        let _guard = EnvGuard::new(&temp_root);
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        fs::create_dir_all(config_path.parent().unwrap()).unwrap();
+        fs::write(
+            &config_path,
+            "base_url = \"https://api.from-config.local/v1\"\n",
+        )
+        .unwrap();
+
+        let mut app = create_test_app();
+        let result = config_command(&mut app, Some("base_url"));
+        let msg = result.message.unwrap();
+
+        assert_eq!(msg, "base_url = https://api.from-config.local/v1");
+    }
+
+    #[test]
+    fn config_command_base_url_reads_current_value_from_app_config_path() {
+        let temp_root = env::temp_dir().join(format!(
+            "deepseek-tui-base-url-app-config-path-test-{}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&temp_root).unwrap();
+
+        let config_path = temp_root.join("custom-config.toml");
+        fs::write(
+            &config_path,
+            "base_url = \"https://api.from-app-path.local/v1\"\n",
+        )
+        .unwrap();
+
+        let mut app = create_test_app();
+        app.config_path = Some(config_path.clone());
+        let result = config_command(&mut app, Some("base_url"));
+        let msg = result.message.unwrap();
+
+        assert_eq!(msg, "base_url = https://api.from-app-path.local/v1");
+    }
+
+    #[test]
+    fn config_command_base_url_save_persists_to_app_config_path() {
+        let temp_root = env::temp_dir().join(format!(
+            "deepseek-tui-base-url-save-app-path-test-{}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&temp_root).unwrap();
+
+        let config_path = temp_root.join("custom-config.toml");
+
+        let mut app = create_test_app();
+        app.config_path = Some(config_path.clone());
+        let result = config_command(
+            &mut app,
+            Some("base_url https://example.session.local/v1 --save"),
+        );
+        let msg = result.message.unwrap();
+        let saved = fs::read_to_string(&config_path).unwrap();
+
+        assert_eq!(
+            msg,
+            format!(
+                "base_url = https://example.session.local/v1 (saved to {})",
+                config_path.display()
+            )
+        );
+        assert!(saved.contains("base_url = \"https://example.session.local/v1\""));
+    }
+
     #[test]
     fn theme_command_accepts_grayscale_arg() {
         let nanos = SystemTime::now()
diff --git a/crates/tui/src/commands/core.rs b/crates/tui/src/commands/core.rs
index 9e8fd775..44394485 100644
--- a/crates/tui/src/commands/core.rs
+++ b/crates/tui/src/commands/core.rs
@@ -46,6 +46,28 @@ pub fn help(app: &mut App, topic: Option<&str>) -> CommandResult {
 
 /// Clear conversation history
 pub fn clear(app: &mut App) -> CommandResult {
+    let todos_cleared = reset_conversation_state(app);
+    app.current_session_id = None;
+    let locale = app.ui_locale;
+    let message = if todos_cleared {
+        tr(locale, MessageId::ClearConversation).to_string()
+    } else {
+        tr(locale, MessageId::ClearConversationBusy).to_string()
+    };
+    CommandResult::with_message_and_action(
+        message,
+        AppAction::SyncSession {
+            session_id: None,
+            messages: Vec::new(),
+            system_prompt: None,
+            model: app.model.clone(),
+            workspace: app.workspace.clone(),
+        },
+    )
+}
+
+/// Reset the active conversation without choosing the next session id.
+pub(crate) fn reset_conversation_state(app: &mut App) -> bool {
     app.clear_history();
     app.mark_history_updated();
     app.api_messages.clear();
@@ -55,6 +77,7 @@ pub fn clear(app: &mut App) -> CommandResult {
     app.queued_draft = None;
     app.session.total_tokens = 0;
     app.session.total_conversation_tokens = 0;
+    app.session.reset_token_breakdown();
     app.session.session_cost = 0.0;
     app.session.session_cost_cny = 0.0;
     app.session.subagent_cost = 0.0;
@@ -77,23 +100,7 @@ pub fn clear(app: &mut App) -> CommandResult {
     app.session.last_reasoning_replay_tokens = None;
     app.session.turn_cache_history.clear();
     app.session.last_cache_inspection = None;
-    app.current_session_id = None;
-    let locale = app.ui_locale;
-    let message = if todos_cleared {
-        tr(locale, MessageId::ClearConversation).to_string()
-    } else {
-        tr(locale, MessageId::ClearConversationBusy).to_string()
-    };
-    CommandResult::with_message_and_action(
-        message,
-        AppAction::SyncSession {
-            session_id: None,
-            messages: Vec::new(),
-            system_prompt: None,
-            model: app.model.clone(),
-            workspace: app.workspace.clone(),
-        },
-    )
+    todos_cleared
 }
 
 /// Exit the application
diff --git a/crates/tui/src/commands/debug.rs b/crates/tui/src/commands/debug.rs
index a89bd174..85b21fae 100644
--- a/crates/tui/src/commands/debug.rs
+++ b/crates/tui/src/commands/debug.rs
@@ -145,6 +145,9 @@ pub fn cache(app: &mut App, arg: Option<&str>) -> CommandResult {
     if matches!(arg, Some("warmup")) {
         return CommandResult::action(AppAction::CacheWarmup);
     }
+    if matches!(arg, Some("stats")) {
+        return CommandResult::message(format_cache_stats(app));
+    }
 
     let want = arg.and_then(|s| s.parse::<usize>().ok()).unwrap_or(10);
     let cap = app.session.turn_cache_history.len();
@@ -233,6 +236,140 @@ fn format_cache_inspect(app: &mut App) -> String {
     out
 }
 
+/// Render a prefix-cache stability and health summary for `/cache stats`.
+///
+/// Surfaces the current prefix fingerprint, stability ratio, change history,
+/// and an aggregated cache-hit summary from per-turn telemetry.  When the
+/// prefix has changed, a prominent warning is included so users can
+/// correlate cache misses with prefix drift.
+fn format_cache_stats(app: &App) -> String {
+    let mut out = String::new();
+    out.push_str("Cache Stats\n");
+
+    // ── Prefix stability ──────────────────────────────────────────────
+    out.push_str("\n── Prefix Stability\n");
+    match app.prefix_stability_pct {
+        Some(pct) => {
+            let checks = app.prefix_checks_total;
+            let changes = app.prefix_change_count;
+            let stable_checks = checks.saturating_sub(changes);
+
+            if changes == 0 {
+                out.push_str(&format!(
+                    "  Stability: {pct}% ({stable_checks}/{checks} checks)\n"
+                ));
+                out.push_str("  Status:    stable (no prefix changes this session)\n");
+            } else {
+                out.push_str(&format!(
+                    "  Stability: {pct}% ({stable_checks}/{checks} checks, {changes} change{})\n",
+                    if changes == 1 { "" } else { "s" }
+                ));
+                out.push_str("  Status:    WARNING — prefix has changed\n");
+                if let Some(ref desc) = app.last_prefix_change_desc {
+                    out.push_str(&format!("  Last change: {desc}\n"));
+                }
+            }
+        }
+        None => {
+            out.push_str("  Stability: unknown (no checks recorded yet)\n");
+            out.push_str("  Run a turn first to collect prefix stability data.\n");
+        }
+    }
+
+    // ── Prefix fingerprint ────────────────────────────────────────────
+    out.push_str("\n── Prefix Fingerprint\n");
+    match &app.last_pinned_prefix_hash {
+        Some(hash) => {
+            out.push_str(&format!("  Pinned hash: {hash}\n"));
+            let short = if hash.len() >= 12 { &hash[..12] } else { hash };
+            out.push_str(&format!("  Short id:    {short}\n"));
+            if app.prefix_change_count > 0 {
+                out.push_str("  Drift:       WARNING — hash has changed during this session\n");
+                out.push_str(&format!(
+                    "               ({change} change{plural} detected)\n",
+                    change = app.prefix_change_count,
+                    plural = if app.prefix_change_count == 1 {
+                        ""
+                    } else {
+                        "s"
+                    }
+                ));
+            } else {
+                out.push_str("  Drift:       none (hash stable)\n");
+            }
+        }
+        None => {
+            out.push_str("  Pinned hash: unavailable\n");
+            out.push_str("  Run a turn first, or use /cache inspect.\n");
+        }
+    }
+
+    // ── Cache hit-rate summary ────────────────────────────────────────
+    out.push_str("\n── Cache Hit Rate\n");
+    let history = &app.session.turn_cache_history;
+    if history.is_empty() {
+        out.push_str("  No turn telemetry recorded yet.\n");
+    } else {
+        // Aggregate only cache-aware turns; skip turns where the provider
+        // did not report cache telemetry (cache_hit_tokens is None).
+        // When cache_miss_tokens is None, infer it as
+        //   input_tokens − cache_hit_tokens  (matches /cache table logic).
+        let mut turns = 0u64;
+        let (hit, miss, input) = app.session.turn_cache_history.iter().fold(
+            (0u64, 0u64, 0u64),
+            |(hit, miss, input), rec| {
+                let Some(hit_tokens) = rec.cache_hit_tokens else {
+                    return (hit, miss, input);
+                };
+                let h = u64::from(hit_tokens);
+                let m = u64::from(
+                    rec.cache_miss_tokens
+                        .unwrap_or(rec.input_tokens.saturating_sub(hit_tokens)),
+                );
+                turns += 1;
+                (hit + h, miss + m, input + u64::from(rec.input_tokens))
+            },
+        );
+        let total_cache = hit + miss;
+        let avg_pct = if total_cache > 0 {
+            (hit as f64 / total_cache as f64 * 100.0).clamp(0.0, 100.0)
+        } else {
+            0.0
+        };
+        out.push_str(&format!("  Turns recorded: {turns}\n"));
+        out.push_str(&format!(
+            "  Cache hit tokens:  {hit} ({avg_pct:.1}% of {total_cache} cache-aware tokens)\n",
+            hit = format_tokens(hit),
+            total_cache = format_tokens(total_cache),
+        ));
+        out.push_str(&format!(
+            "  Cache miss tokens: {miss}\n",
+            miss = format_tokens(miss),
+        ));
+        out.push_str(&format!(
+            "  Total input tokens: {input}\n",
+            input = format_tokens(input),
+        ));
+        if avg_pct < 80.0 {
+            out.push_str("  NOTE: cache hit rate is low (< 80%). Check prefix stability above or consider /compact.\n");
+        }
+    }
+
+    out
+}
+
+/// Formats a u64 token count with a compact suffix: K for thousands,
+/// M for millions. Never returns scientific notation.
+fn format_tokens(n: u64) -> String {
+    if n >= 1_000_000 {
+        format!("{:.1}M", n as f64 / 1_000_000.0)
+    } else if n >= 1_000 {
+        format!("{:.1}K", n as f64 / 1_000.0)
+    } else {
+        n.to_string()
+    }
+}
+
 fn format_static_prefix_status(
     previous: Option<&PromptInspection>,
     current: &PromptInspection,
@@ -1402,6 +1539,136 @@ mod tests {
             ContentBlock::ToolResult { tool_use_id, .. } if tool_use_id == "call-a"
         ));
     }
+
+    // ── /cache stats tests ──────────────────────────────────────────────
+
+    #[test]
+    fn cache_stats_no_data_before_first_turn() {
+        let mut app = create_test_app();
+        let result = cache(&mut app, Some("stats"));
+        let msg = result.message.expect("cache stats produces a message");
+        assert!(msg.contains("Cache Stats"), "got: {msg}");
+        assert!(
+            msg.contains("unknown (no checks recorded yet)"),
+            "got: {msg}"
+        );
+        assert!(msg.contains("Pinned hash: unavailable"), "got: {msg}");
+        assert!(msg.contains("No turn telemetry recorded yet"), "got: {msg}");
+    }
+
+    #[test]
+    fn cache_stats_shows_stable_prefix_with_hash() {
+        let mut app = create_test_app();
+        app.prefix_stability_pct = Some(100);
+        app.prefix_checks_total = 5;
+        app.prefix_change_count = 0;
+        app.last_pinned_prefix_hash =
+            Some("a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2".to_string());
+
+        let result = cache(&mut app, Some("stats"));
+        let msg = result.message.expect("cache stats produces a message");
+
+        assert!(msg.contains("Stability: 100%"), "got: {msg}");
+        assert!(msg.contains("stable (no prefix changes"), "got: {msg}");
+        assert!(msg.contains("Pinned hash: a1b2c3d4e5f6"), "got: {msg}");
+        assert!(
+            msg.contains("Drift:       none (hash stable)"),
+            "got: {msg}"
+        );
+    }
+
+    #[test]
+    fn cache_stats_warns_on_prefix_change() {
+        let mut app = create_test_app();
+        app.prefix_stability_pct = Some(67);
+        app.prefix_checks_total = 3;
+        app.prefix_change_count = 1;
+        app.last_prefix_change_desc =
+            Some("prefix cache invalidated: system prompt changed".to_string());
+        app.last_pinned_prefix_hash = Some(
+            "deadbeef0000deadbeef0000deadbeef0000deadbeef0000deadbeef0000deadbeef".to_string(),
+        );
+
+        let result = cache(&mut app, Some("stats"));
+        let msg = result.message.expect("cache stats produces a message");
+
+        assert!(msg.contains("Stability: 67%"), "got: {msg}");
+        assert!(msg.contains("WARNING — prefix has changed"), "got: {msg}");
+        assert!(msg.contains("system prompt changed"), "got: {msg}");
+        assert!(msg.contains("Drift:       WARNING"), "got: {msg}");
+        assert!(msg.contains("1 change detected"), "got: {msg}");
+    }
+
+    #[test]
+    fn cache_stats_shows_cache_hit_summary() {
+        let mut app = create_test_app();
+        app.prefix_stability_pct = Some(100);
+        app.prefix_checks_total = 1;
+        app.last_pinned_prefix_hash =
+            Some("abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234".to_string());
+
+        app.push_turn_cache_record(TurnCacheRecord {
+            input_tokens: 10_000,
+            output_tokens: 1_000,
+            cache_hit_tokens: Some(8_000),
+            cache_miss_tokens: Some(2_000),
+            reasoning_replay_tokens: None,
+            recorded_at: Instant::now(),
+        });
+        app.push_turn_cache_record(TurnCacheRecord {
+            input_tokens: 5_000,
+            output_tokens: 500,
+            cache_hit_tokens: Some(4_500),
+            cache_miss_tokens: Some(500),
+            reasoning_replay_tokens: None,
+            recorded_at: Instant::now(),
+        });
+
+        let result = cache(&mut app, Some("stats"));
+        let msg = result.message.expect("cache stats produces a message");
+
+        assert!(msg.contains("Turns recorded: 2"), "got: {msg}");
+        // Total: 12,500 hit out of 15,000 cache-aware = 83.3%
+        assert!(msg.contains("83.3%"), "got: {msg}");
+    }
+
+    #[test]
+    fn cache_stats_low_hit_rate_shows_note() {
+        let mut app = create_test_app();
+        app.prefix_stability_pct = Some(100);
+        app.prefix_checks_total = 1;
+        app.last_pinned_prefix_hash =
+            Some("abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234".to_string());
+
+        app.push_turn_cache_record(TurnCacheRecord {
+            input_tokens: 10_000,
+            output_tokens: 1_000,
+            cache_hit_tokens: Some(1_000),
+            cache_miss_tokens: Some(9_000),
+            reasoning_replay_tokens: None,
+            recorded_at: Instant::now(),
+        });
+
+        let result = cache(&mut app, Some("stats"));
+        let msg = result.message.expect("cache stats produces a message");
+
+        // 10% hit rate → below 80% threshold
+        assert!(msg.contains("10.0%"), "got: {msg}");
+        assert!(
+            msg.contains("cache hit rate is low"),
+            "should show low-hit-rate advisory, got: {msg}"
+        );
+    }
+
+    #[test]
+    fn format_tokens_handles_all_scales() {
+        assert_eq!(format_tokens(0), "0");
+        assert_eq!(format_tokens(999), "999");
+        assert_eq!(format_tokens(1_000), "1.0K");
+        assert_eq!(format_tokens(15_500), "15.5K");
+        assert_eq!(format_tokens(1_000_000), "1.0M");
+        assert_eq!(format_tokens(2_500_000), "2.5M");
+    }
 }
 
 /// Remove last message pair (user + assistant).
diff --git a/crates/tui/src/commands/goal.rs b/crates/tui/src/commands/goal.rs
index 47a4d62e..bb07c5b5 100644
--- a/crates/tui/src/commands/goal.rs
+++ b/crates/tui/src/commands/goal.rs
@@ -1,56 +1,51 @@
-//! /goal command — set a session objective with token budget and progress tracking.
+//! /hunt command — declare a quarry with token budget and verdict tracking (#2092).
 
-use crate::tui::app::App;
+use std::io::Write;
+
+use crate::tui::app::{App, AppAction, HuntVerdict};
 
 use super::CommandResult;
 
-/// Set or show the current goal
-pub fn goal(app: &mut App, arg: Option<&str>) -> CommandResult {
+/// Declare, show, or close a hunt
+pub fn hunt(app: &mut App, arg: Option<&str>) -> CommandResult {
     match arg {
         Some("clear") | Some("reset") => {
-            app.goal.goal_objective = None;
-            app.goal.goal_token_budget = None;
-            app.goal.goal_started_at = None;
-            app.goal.goal_completed = false;
-            CommandResult::message("Goal cleared.")
-        }
-        Some("done") | Some("complete") => {
-            app.goal.goal_completed = true;
-            let elapsed = app
-                .goal
-                .goal_started_at
-                .map(|t| crate::tui::notifications::humanize_duration(t.elapsed()))
-                .unwrap_or_else(|| "unknown".to_string());
-            CommandResult::message(format!("Goal marked complete! Elapsed: {elapsed}"))
+            app.hunt.quarry = None;
+            app.hunt.token_budget = None;
+            app.hunt.started_at = None;
+            app.hunt.verdict = HuntVerdict::default();
+            CommandResult::message("Hunt cleared.")
         }
+        Some("done") | Some("complete") | Some("hunted") => close_hunt(app, HuntVerdict::Hunted),
+        Some("wound") | Some("wounded") => close_hunt(app, HuntVerdict::Wounded),
+        Some("escape") | Some("escaped") => close_hunt(app, HuntVerdict::Escaped),
         Some(text) if !text.is_empty() => {
-            // Parse optional budget: "/goal Implement login | budget: 50000"
-            let (objective, budget) = parse_goal_budget(text);
-            app.goal.goal_objective = Some(objective.clone());
-            app.goal.goal_token_budget = budget;
-            app.goal.goal_started_at = Some(std::time::Instant::now());
-            app.goal.goal_completed = false;
+            let (objective, budget) = parse_hunt_budget(text);
+            if objective.is_empty() || objective.chars().all(|c| c == '|') {
+                return CommandResult::error("Usage: /hunt <quarry> [budget: N]");
+            }
+            app.hunt.quarry = Some(objective.clone());
+            app.hunt.token_budget = budget;
+            app.hunt.started_at = Some(std::time::Instant::now());
+            app.hunt.verdict = HuntVerdict::Hunting;
             let budget_str = budget
                 .map(|b| format!(" (budget: {b} tokens)"))
                 .unwrap_or_default();
-            CommandResult::message(format!(
-                "Goal set: \"{objective}\"{budget_str} — tracking progress."
-            ))
+            CommandResult::with_message_and_action(
+                format!("Hunt set: \"{objective}\"{budget_str} — tracking progress."),
+                AppAction::SendMessage(objective),
+            )
         }
         _ => {
-            // Show current goal
-            if let Some(ref obj) = app.goal.goal_objective {
-                // #447: render long elapsed times as `2d 3h` rather
-                // than Rust's default Debug `Duration` (which produces
-                // `188415.234s` or similar for multi-day goals).
+            if let Some(ref obj) = app.hunt.quarry {
                 let elapsed = app
-                    .goal
-                    .goal_started_at
+                    .hunt
+                    .started_at
                     .map(|t| crate::tui::notifications::humanize_duration(t.elapsed()))
                     .unwrap_or_else(|| "unknown".to_string());
                 let budget_str = app
-                    .goal
-                    .goal_token_budget
+                    .hunt
+                    .token_budget
                     .map(|b| {
                         let used = app.session.total_conversation_tokens;
                         let pct = if b > 0 {
@@ -61,26 +56,61 @@ pub fn goal(app: &mut App, arg: Option<&str>) -> CommandResult {
                         format!(" | tokens: {used}/{b} ({pct:.0}%)")
                     })
                     .unwrap_or_default();
-                let status = if app.goal.goal_completed {
-                    " [COMPLETED]"
-                } else {
-                    ""
+                let verdict_label = match app.hunt.verdict {
+                    HuntVerdict::Hunting => "[HUNTING]",
+                    HuntVerdict::Hunted => "[HUNTED]",
+                    HuntVerdict::Wounded => "[WOUNDED]",
+                    HuntVerdict::Escaped => "[ESCAPED]",
                 };
                 CommandResult::message(format!(
-                    "Goal{status}: \"{obj}\" — elapsed: {elapsed}{budget_str}"
+                    "Hunt {verdict_label}: \"{obj}\" — elapsed: {elapsed}{budget_str}"
                 ))
             } else {
                 CommandResult::message(
-                    "No goal set. Use /goal <objective> [budget: N] to set one.\n\
-                     /goal clear — remove the current goal.",
+                    "No hunt set. Use /hunt <quarry> [budget: N] to declare one.\n\
+                     /hunt hunted — mark complete\n\
+                     /hunt wounded — mark interrupted (resumable)\n\
+                     /hunt escaped — mark abandoned\n\
+                     /hunt clear — remove the current hunt.",
                 )
             }
         }
     }
 }
 
-/// Parse optional token budget from goal text: "Implement login | budget: 50000"
-fn parse_goal_budget(text: &str) -> (String, Option<u32>) {
+fn close_hunt(app: &mut App, verdict: HuntVerdict) -> CommandResult {
+    if app.hunt.quarry.as_deref().is_none_or(str::is_empty) {
+        return CommandResult::error("No hunt set. Use /hunt <quarry> [budget: N] first.");
+    }
+
+    let prev = app.hunt.verdict;
+    let should_write_trophy = prev != verdict || !matches!(verdict, HuntVerdict::Hunted);
+    if should_write_trophy {
+        if let Err(err) = write_trophy_card(app, verdict) {
+            return CommandResult::error(err);
+        }
+    }
+    app.hunt.verdict = verdict;
+
+    match verdict {
+        HuntVerdict::Hunted => {
+            let elapsed = app
+                .hunt
+                .started_at
+                .map(|t| crate::tui::notifications::humanize_duration(t.elapsed()))
+                .unwrap_or_else(|| "unknown".to_string());
+            CommandResult::message(format!("Hunt complete! Elapsed: {elapsed}"))
+        }
+        HuntVerdict::Wounded => {
+            CommandResult::message("Hunt wounded — progress saved, can be resumed.")
+        }
+        HuntVerdict::Escaped => CommandResult::message("Hunt escaped — quarry abandoned."),
+        HuntVerdict::Hunting => CommandResult::message("Hunt resumed."),
+    }
+}
+
+/// Parse text like "Implement login | budget: 50000" into (objective, budget).
+fn parse_hunt_budget(text: &str) -> (String, Option<u32>) {
     if let Some((obj, rest)) = text.split_once(" | budget:") {
         let budget = rest
             .split_whitespace()
@@ -98,17 +128,114 @@ fn parse_goal_budget(text: &str) -> (String, Option<u32>) {
     }
 }
 
+/// Write a trophy card to `~/.codewhale/trophies/<date>-<time>-<slug>.md`
+/// for the current hunt verdict (#2092).
+fn write_trophy_card(app: &App, verdict: HuntVerdict) -> Result<std::path::PathBuf, String> {
+    let quarry = app
+        .hunt
+        .quarry
+        .as_deref()
+        .ok_or_else(|| "No hunt set. Use /hunt <quarry> [budget: N] first.".to_string())?;
+    // Collapse consecutive non-alphanumeric chars into a single '-'
+    let mut slug = String::new();
+    let mut last_dash = false;
+    for c in quarry.chars() {
+        if c.is_alphanumeric() {
+            slug.push(c.to_ascii_lowercase());
+            last_dash = false;
+        } else if !last_dash {
+            slug.push('-');
+            last_dash = true;
+        }
+    }
+    let slug = slug.trim_matches('-');
+    if slug.is_empty() {
+        return Err(
+            "Cannot write trophy card: hunt quarry has no filename-safe characters.".into(),
+        );
+    }
+    let now = chrono::Local::now();
+    let time = now.format("%H%M%S");
+    let date = now.format("%Y-%m-%d");
+    let date_str = date.to_string();
+    let now_str = now.to_string();
+    let dir = codewhale_config::resolve_state_dir("trophies")
+        .map_err(|err| format!("Could not resolve trophy directory: {err}"))?;
+    std::fs::create_dir_all(&dir)
+        .map_err(|err| format!("Could not create trophy directory {}: {err}", dir.display()))?;
+    // Include time in filename to avoid collisions on same-date hunts.
+    let filename = format!("{date}-{time}-{slug}.md");
+    let path = dir.join(&filename);
+
+    let elapsed = app
+        .hunt
+        .started_at
+        .as_ref()
+        .map(|t| crate::tui::notifications::humanize_duration(t.elapsed()))
+        .unwrap_or_else(|| "unknown".to_string());
+    let verdict_str = match verdict {
+        HuntVerdict::Hunting => "hunting",
+        HuntVerdict::Hunted => "hunted",
+        HuntVerdict::Wounded => "wounded",
+        HuntVerdict::Escaped => "escaped",
+    };
+    let tokens = app.session.total_conversation_tokens;
+    let budget_str = app
+        .hunt
+        .token_budget
+        .map(|b| format!("{b}"))
+        .unwrap_or_else(|| "—".to_string());
+
+    let mut f = std::fs::File::create(&path)
+        .map_err(|err| format!("Could not create trophy card {}: {err}", path.display()))?;
+    write_trophy_card_contents(
+        &mut f,
+        TrophyCard {
+            quarry,
+            verdict: verdict_str,
+            date: &date_str,
+            elapsed: &elapsed,
+            tokens,
+            budget: &budget_str,
+            now: &now_str,
+        },
+    )
+    .map_err(|err| format!("Could not write trophy card {}: {err}", path.display()))?;
+
+    Ok(path)
+}
+
+struct TrophyCard<'a> {
+    quarry: &'a str,
+    verdict: &'a str,
+    date: &'a str,
+    elapsed: &'a str,
+    tokens: u32,
+    budget: &'a str,
+    now: &'a str,
+}
+
+fn write_trophy_card_contents(mut f: impl Write, card: TrophyCard<'_>) -> std::io::Result<()> {
+    writeln!(f, "# Trophy: {}", card.quarry)?;
+    writeln!(f)?;
+    writeln!(f, "- **Verdict**: {}", card.verdict)?;
+    writeln!(f, "- **Date**: {}", card.date)?;
+    writeln!(f, "- **Elapsed**: {}", card.elapsed)?;
+    writeln!(f, "- **Tokens used**: {}", card.tokens)?;
+    writeln!(f, "- **Token budget**: {}", card.budget)?;
+    writeln!(f)?;
+    writeln!(f, "_Generated by CodeWhale `/hunt` — {}_", card.now)?;
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::config::Config;
-    use crate::tui::app::{App, TuiOptions};
-    use std::path::PathBuf;
 
     fn create_test_app() -> App {
-        let options = TuiOptions {
-            model: "deepseek-v4-flash".to_string(),
-            workspace: PathBuf::from("."),
+        let options = crate::tui::app::TuiOptions {
+            model: "deepseek-v4-pro".to_string(),
+            workspace: std::path::PathBuf::from("/tmp/test-workspace"),
             config_path: None,
             config_profile: None,
             allow_shell: false,
@@ -116,67 +243,121 @@ mod tests {
             use_mouse_capture: false,
             use_bracketed_paste: true,
             max_subagents: 1,
-            skills_dir: PathBuf::from("."),
-            memory_path: PathBuf::from("memory.md"),
-            notes_path: PathBuf::from("notes.txt"),
-            mcp_config_path: PathBuf::from("mcp.json"),
+            skills_dir: std::path::PathBuf::from("/tmp/test-skills"),
+            memory_path: std::path::PathBuf::from("memory.md"),
+            notes_path: std::path::PathBuf::from("notes.txt"),
+            mcp_config_path: std::path::PathBuf::from("mcp.json"),
             use_memory: false,
-            start_in_agent_mode: true,
+            start_in_agent_mode: false,
             skip_onboarding: true,
-            yolo: false,
-            resume_session_id: None,
             initial_input: None,
+            resume_session_id: None,
+            yolo: false,
         };
-        App::new(options, &Config::default())
+        let config = crate::config::Config::default();
+        App::new(options, &config)
     }
 
     #[test]
-    fn test_set_goal() {
+    fn test_set_hunt() {
         let mut app = create_test_app();
-        let result = goal(&mut app, Some("Fix the login bug"));
-        assert!(result.message.unwrap().contains("Goal set"));
-        assert_eq!(
-            app.goal.goal_objective.as_deref(),
-            Some("Fix the login bug")
+        let result = hunt(&mut app, Some("Fix the login bug"));
+        assert!(result.message.unwrap().contains("Hunt set"));
+        assert_eq!(app.hunt.quarry.as_deref(), Some("Fix the login bug"));
+        assert!(matches!(
+            result.action,
+            Some(AppAction::SendMessage(msg)) if msg == "Fix the login bug"
+        ));
+    }
+
+    #[test]
+    fn test_hunt_without_argument_shows_state() {
+        let mut app = create_test_app();
+        let result = hunt(&mut app, None);
+        assert!(result.action.is_none());
+        assert!(result.message.as_deref().unwrap().contains("No hunt set"));
+    }
+
+    #[test]
+    fn test_set_hunt_with_budget() {
+        let mut app = create_test_app();
+        let _ = hunt(&mut app, Some("Refactor auth | budget: 50000"));
+        assert_eq!(app.hunt.quarry.as_deref(), Some("Refactor auth"));
+        assert_eq!(app.hunt.token_budget, Some(50_000));
+        assert!(app.hunt.started_at.is_some());
+    }
+
+    #[test]
+    fn test_set_hunt_rejects_budget_only_objective() {
+        let mut app = create_test_app();
+        app.hunt.quarry = Some("existing objective".to_string());
+        app.hunt.token_budget = Some(10_000);
+
+        let result = hunt(&mut app, Some("budget: 50000"));
+        assert!(result.is_error);
+        assert!(
+            result
+                .message
+                .as_deref()
+                .unwrap_or_default()
+                .contains("Usage: /hunt")
         );
+        assert_eq!(app.hunt.quarry.as_deref(), Some("existing objective"));
+        assert_eq!(app.hunt.token_budget, Some(10_000));
     }
 
     #[test]
-    fn test_set_goal_with_budget() {
+    fn test_clear_hunt() {
         let mut app = create_test_app();
-        let _ = goal(&mut app, Some("Refactor auth | budget: 50000"));
-        assert_eq!(app.goal.goal_objective.as_deref(), Some("Refactor auth"));
-        assert_eq!(app.goal.goal_token_budget, Some(50_000));
+        app.hunt.quarry = Some("test".to_string());
+        let _ = hunt(&mut app, Some("clear"));
+        assert!(app.hunt.quarry.is_none());
+        assert!(app.hunt.token_budget.is_none());
     }
 
     #[test]
-    fn test_clear_goal() {
+    fn test_verdict_requires_existing_hunt() {
         let mut app = create_test_app();
-        app.goal.goal_objective = Some("test".to_string());
-        let _ = goal(&mut app, Some("clear"));
-        assert!(app.goal.goal_objective.is_none());
-        assert!(app.goal.goal_token_budget.is_none());
+
+        let result = hunt(&mut app, Some("wounded"));
+
+        assert!(result.is_error);
+        assert_eq!(app.hunt.verdict, HuntVerdict::Hunting);
+        assert!(app.hunt.quarry.is_none());
     }
 
     #[test]
-    fn test_show_goal_when_none() {
+    fn test_failed_trophy_write_does_not_mutate_verdict() {
         let mut app = create_test_app();
-        let result = goal(&mut app, None);
-        assert!(result.message.unwrap().contains("No goal set"));
+        app.hunt.quarry = Some("!!!".to_string());
+        app.hunt.verdict = HuntVerdict::Hunting;
+
+        let result = hunt(&mut app, Some("escaped"));
+
+        assert!(result.is_error);
+        assert_eq!(app.hunt.verdict, HuntVerdict::Hunting);
+        assert_eq!(app.hunt.quarry.as_deref(), Some("!!!"));
+    }
+
+    #[test]
+    fn test_show_hunt_when_none() {
+        let mut app = create_test_app();
+        let result = hunt(&mut app, None);
+        assert!(result.message.unwrap().contains("No hunt set"));
     }
 
     #[test]
     fn test_parse_budget() {
         assert_eq!(
-            parse_goal_budget("Do a thing | budget: 50000"),
+            parse_hunt_budget("Do a thing | budget: 50000"),
             ("Do a thing".to_string(), Some(50_000))
         );
         assert_eq!(
-            parse_goal_budget("Simple goal"),
+            parse_hunt_budget("Simple goal"),
             ("Simple goal".to_string(), None)
         );
         assert_eq!(
-            parse_goal_budget("Goal budget:1000"),
+            parse_hunt_budget("Goal budget:1000"),
             ("Goal".to_string(), Some(1000))
         );
     }
diff --git a/crates/tui/src/commands/mcp.rs b/crates/tui/src/commands/mcp.rs
index 2a29f729..7edf9500 100644
--- a/crates/tui/src/commands/mcp.rs
+++ b/crates/tui/src/commands/mcp.rs
@@ -56,9 +56,15 @@ fn parse_add(parts: Vec<&str>) -> CommandResult {
             command: parts[2].to_string(),
             args: parts[3..].iter().map(|s| (*s).to_string()).collect(),
         })),
-        "http" | "sse" => CommandResult::action(AppAction::Mcp(McpUiAction::AddHttp {
+        "http" => CommandResult::action(AppAction::Mcp(McpUiAction::AddHttp {
             name: parts[1].to_string(),
             url: parts[2].to_string(),
+            transport: None,
+        })),
+        "sse" => CommandResult::action(AppAction::Mcp(McpUiAction::AddHttp {
+            name: parts[1].to_string(),
+            url: parts[2].to_string(),
+            transport: Some("sse".to_string()),
         })),
         _ => CommandResult::error(
             "Usage: /mcp add stdio <name> <command> [args...] OR /mcp add http <name> <url>",
diff --git a/crates/tui/src/commands/mod.rs b/crates/tui/src/commands/mod.rs
index b1e9f3dd..8db11743 100644
--- a/crates/tui/src/commands/mod.rs
+++ b/crates/tui/src/commands/mod.rs
@@ -31,7 +31,7 @@ mod skills;
 mod stash;
 mod status;
 mod task;
-mod user_commands;
+pub mod user_commands;
 
 use std::fmt::Write as _;
 
@@ -298,6 +298,12 @@ pub const COMMANDS: &[CommandInfo] = &[
         usage: "/fork",
         description_id: MessageId::CmdForkDescription,
     },
+    CommandInfo {
+        name: "new",
+        aliases: &[],
+        usage: "/new [--force]",
+        description_id: MessageId::CmdNewDescription,
+    },
     CommandInfo {
         name: "sessions",
         aliases: &["resume"],
@@ -316,6 +322,12 @@ pub const COMMANDS: &[CommandInfo] = &[
         usage: "/compact",
         description_id: MessageId::CmdCompactDescription,
     },
+    CommandInfo {
+        name: "purge",
+        aliases: &["qingchu"],
+        usage: "/purge",
+        description_id: MessageId::CmdPurgeDescription,
+    },
     CommandInfo {
         name: "relay",
         aliases: &["batonpass", "接力"],
@@ -457,9 +469,9 @@ pub const COMMANDS: &[CommandInfo] = &[
         description_id: MessageId::CmdShareDescription,
     },
     CommandInfo {
-        name: "goal",
-        aliases: &["mubiao"],
-        usage: "/goal [objective] [budget: N]",
+        name: "hunt",
+        aliases: &["goal", "mubiao", "狩猎"],
+        usage: "/hunt [quarry] [budget: N]",
         description_id: MessageId::CmdGoalDescription,
     },
     CommandInfo {
@@ -537,9 +549,16 @@ pub const COMMANDS: &[CommandInfo] = &[
     CommandInfo {
         name: "cache",
         aliases: &[],
-        usage: "/cache [count|inspect|warmup]",
+        usage: "/cache [count|inspect|stats|warmup]",
         description_id: MessageId::CmdCacheDescription,
     },
+    // Slop Ledger (#2127)
+    CommandInfo {
+        name: "slop",
+        aliases: &["canzha"],
+        usage: "/slop [query|export]",
+        description_id: MessageId::CmdSlopDescription,
+    },
 ];
 
 /// Execute a slash command
@@ -585,10 +604,12 @@ pub fn execute(cmd: &str, app: &mut App) -> CommandResult {
         "rename" | "gaiming" | "chongmingming" => rename::rename(app, arg),
         "save" => session::save(app, arg),
         "fork" | "branch" => session::fork(app),
+        "new" => session::new_session(app, arg),
         "sessions" | "resume" => session::sessions(app, arg),
         "relay" | "batonpass" | "接力" => relay(app, arg),
         "load" | "jiazai" => session::load(app, arg),
         "compact" | "yasuo" => session::compact(app),
+        "purge" | "qingchu" => session::purge(app),
         "cycles" | "zhouqi" => cycle::list_cycles(app),
         "cycle" => cycle::show_cycle(app, arg),
         "recall" => cycle::recall_archive(app, arg),
@@ -614,6 +635,9 @@ pub fn execute(cmd: &str, app: &mut App) -> CommandResult {
         "balance" => balance::balance(app),
         "cache" => debug::cache(app, arg),
 
+        // Slop ledger (#2127)
+        "slop" | "canzha" => config::slop(app, arg),
+
         // ChangeLog command
         "change" => change::change(app, arg),
         "system" | "xitong" => debug::system_prompt(app),
@@ -641,7 +665,7 @@ pub fn execute(cmd: &str, app: &mut App) -> CommandResult {
         "init" => init::init(app),
         "lsp" => config::lsp_command(app, arg),
         "share" => share::share(app, arg),
-        "goal" | "mubiao" => goal::goal(app, arg),
+        "goal" | "hunt" | "mubiao" | "狩猎" => goal::hunt(app, arg),
 
         // Skills commands
         "skills" | "jinengliebiao" => skills::list_skills(app, arg),
@@ -702,8 +726,12 @@ pub fn persist_status_items(
 }
 
 /// Persist a root-level string key in `config.toml`.
-pub fn persist_root_string_key(key: &str, value: &str) -> anyhow::Result<std::path::PathBuf> {
-    config::persist_root_string_key(key, value)
+pub fn persist_root_string_key(
+    config_path: Option<&std::path::Path>,
+    key: &str,
+    value: &str,
+) -> anyhow::Result<std::path::PathBuf> {
+    config::persist_root_string_key(config_path, key, value)
 }
 
 pub fn switch_mode(app: &mut App, mode: crate::tui::app::AppMode) -> String {
@@ -815,11 +843,11 @@ fn build_relay_instruction(app: &App, focus: Option<&str>) -> String {
     if let Some(focus) = focus {
         let _ = writeln!(out, "- Requested relay focus: {focus}");
     }
-    if let Some(goal) = app.goal.goal_objective.as_deref() {
-        let _ = writeln!(out, "- Goal: {goal}");
+    if let Some(quarry) = app.hunt.quarry.as_deref() {
+        let _ = writeln!(out, "- Hunt quarry: {quarry}");
     }
-    if let Some(budget) = app.goal.goal_token_budget {
-        let _ = writeln!(out, "- Goal token budget: {budget}");
+    if let Some(budget) = app.hunt.token_budget {
+        let _ = writeln!(out, "- Hunt token budget: {budget}");
     }
     if app.cycle_count > 0 {
         let _ = writeln!(out, "- Cycle count: {}", app.cycle_count);
@@ -955,6 +983,7 @@ pub fn get_command_info(name: &str) -> Option<&'static CommandInfo> {
 ///
 /// `workspace` is used to also scan workspace-local command directories;
 /// pass `None` when no workspace context is available.
+#[allow(dead_code)]
 pub fn all_command_names_matching(
     prefix: &str,
     workspace: Option<&std::path::Path>,
@@ -1153,8 +1182,8 @@ mod tests {
     #[test]
     fn relay_slash_command_routes_to_session_relay_instruction() {
         let mut app = create_test_app();
-        app.goal.goal_objective = Some("Unify the work surface".to_string());
-        app.goal.goal_token_budget = Some(12_000);
+        app.hunt.quarry = Some("Unify the work surface".to_string());
+        app.hunt.token_budget = Some(12_000);
         app.cycle_count = 2;
         {
             let mut todos = app.todos.try_lock().expect("todo lock");
@@ -1189,8 +1218,8 @@ mod tests {
         assert!(message.contains("Write or update `.deepseek/handoff.md`"));
         assert!(message.contains("# Session relay"));
         assert!(message.contains("Requested relay focus: verify install"));
-        assert!(message.contains("Goal: Unify the work surface"));
-        assert!(message.contains("Goal token budget: 12000"));
+        assert!(message.contains("Hunt quarry: Unify the work surface"));
+        assert!(message.contains("Hunt token budget: 12000"));
         assert!(message.contains("Cycle count: 2"));
         assert!(message.contains("Work checklist (primary progress surface, 50% complete)"));
         assert!(message.contains("#1 [completed] inspect workspace"));
diff --git a/crates/tui/src/commands/network.rs b/crates/tui/src/commands/network.rs
index 563ded91..dbe0e7af 100644
--- a/crates/tui/src/commands/network.rs
+++ b/crates/tui/src/commands/network.rs
@@ -70,7 +70,7 @@ enum NetworkEdit {
 }
 
 fn list_policy() -> anyhow::Result<String> {
-    let path = super::config::config_toml_path()?;
+    let path = super::config::config_toml_path(None)?;
     let doc = load_config_doc(&path)?;
     let network = doc.get("network").and_then(Value::as_table);
     let default = network
@@ -97,7 +97,7 @@ fn list_policy() -> anyhow::Result<String> {
 }
 
 fn update_host(edit: NetworkEdit, host: &str) -> anyhow::Result<String> {
-    let path = super::config::config_toml_path()?;
+    let path = super::config::config_toml_path(None)?;
     let mut doc = load_config_doc(&path)?;
     let network = network_table_mut(&mut doc)?;
 
@@ -136,7 +136,7 @@ fn update_default(value: &str) -> anyhow::Result<String> {
         _ => bail!("Usage: /network default <allow|deny|prompt>"),
     };
 
-    let path = super::config::config_toml_path()?;
+    let path = super::config::config_toml_path(None)?;
     let mut doc = load_config_doc(&path)?;
     let network = network_table_mut(&mut doc)?;
     network.insert("default".to_string(), Value::String(normalized.to_string()));
diff --git a/crates/tui/src/commands/note.rs b/crates/tui/src/commands/note.rs
index 8aa1267f..6efe4413 100644
--- a/crates/tui/src/commands/note.rs
+++ b/crates/tui/src/commands/note.rs
@@ -39,6 +39,10 @@ pub fn note(app: &mut App, content: Option<&str>) -> CommandResult {
 }
 
 fn notes_path(app: &App) -> PathBuf {
+    let primary = app.workspace.join(".codewhale").join("notes.md");
+    if primary.exists() {
+        return primary;
+    }
     app.workspace.join(".deepseek").join("notes.md")
 }
 
diff --git a/crates/tui/src/commands/provider.rs b/crates/tui/src/commands/provider.rs
index 915cce8c..6caaacc9 100644
--- a/crates/tui/src/commands/provider.rs
+++ b/crates/tui/src/commands/provider.rs
@@ -27,7 +27,7 @@ pub fn provider(app: &mut App, args: Option<&str>) -> CommandResult {
 
     let Some(target) = ApiProvider::parse(name) else {
         return CommandResult::error(format!(
-            "Unknown provider '{name}'. Expected: deepseek, nvidia-nim, openai, atlascloud, wanjie-ark, openrouter, novita, fireworks, sglang, vllm, or ollama."
+            "Unknown provider '{name}'. Expected: deepseek, nvidia-nim, openai, atlascloud, wanjie-ark, openrouter, xiaomi-mimo, novita, fireworks, sglang, vllm, or ollama."
         ));
     };
 
@@ -112,6 +112,7 @@ mod tests {
         let msg = result.message.expect("expected error message");
         assert!(msg.contains("Unknown provider"));
         assert!(msg.contains("openrouter"));
+        assert!(msg.contains("xiaomi-mimo"));
         assert!(msg.contains("novita"));
         assert!(result.action.is_none());
     }
@@ -129,6 +130,19 @@ mod tests {
         }
     }
 
+    #[test]
+    fn switch_to_xiaomi_mimo_emits_action() {
+        let mut app = create_test_app();
+        let result = provider(&mut app, Some("xiaomi-mimo"));
+        match result.action {
+            Some(AppAction::SwitchProvider { provider, model }) => {
+                assert_eq!(provider, ApiProvider::XiaomiMimo);
+                assert_eq!(model, None);
+            }
+            other => panic!("expected SwitchProvider, got {other:?}"),
+        }
+    }
+
     #[test]
     fn switch_to_atlascloud_emits_action() {
         let mut app = create_test_app();
diff --git a/crates/tui/src/commands/session.rs b/crates/tui/src/commands/session.rs
index 7a107797..ac03487c 100644
--- a/crates/tui/src/commands/session.rs
+++ b/crates/tui/src/commands/session.rs
@@ -133,6 +133,73 @@ pub fn fork(app: &mut App) -> CommandResult {
     )
 }
 
+/// Start a fresh saved session from the current TUI state.
+pub fn new_session(app: &mut App, arg: Option<&str>) -> CommandResult {
+    let force = match arg.map(str::trim).filter(|s| !s.is_empty()) {
+        None => false,
+        Some("--force" | "force") => true,
+        Some(other) => {
+            return CommandResult::error(format!(
+                "Usage: /new [--force]\n\nUnknown argument: {other}"
+            ));
+        }
+    };
+
+    if !force {
+        let blockers = new_session_blockers(app);
+        if !blockers.is_empty() {
+            return CommandResult::error(format!(
+                "Cannot start a new session while {}. Run `/new --force` to discard pending work and start a fresh session.",
+                blockers.join(", ")
+            ));
+        }
+    }
+
+    let new_id = uuid::Uuid::new_v4().to_string();
+    super::core::reset_conversation_state(app);
+    app.clear_input();
+    app.session_artifacts.clear();
+    app.session_context_references.clear();
+    app.tool_evidence.clear();
+    app.current_session_id = Some(new_id.clone());
+    app.session_title = Some("New Session".to_string());
+    app.scroll_to_bottom();
+
+    CommandResult::with_message_and_action(
+        format!(
+            "Started new session {} (New Session). Previous sessions remain available via /resume.",
+            crate::session_manager::truncate_id(&new_id)
+        ),
+        AppAction::SyncSession {
+            session_id: Some(new_id),
+            messages: Vec::new(),
+            system_prompt: None,
+            model: app.model.clone(),
+            workspace: app.workspace.clone(),
+        },
+    )
+}
+
+fn new_session_blockers(app: &App) -> Vec<&'static str> {
+    let mut blockers = Vec::new();
+    if !app.input.trim().is_empty() {
+        blockers.push("the composer has unsent text");
+    }
+    if !app.queued_messages.is_empty() || app.queued_draft.is_some() {
+        blockers.push("queued messages are pending");
+    }
+    if app.is_loading || app.runtime_turn_status.as_deref() == Some("in_progress") {
+        blockers.push("a turn is in progress");
+    }
+    if app.is_compacting {
+        blockers.push("context compaction is running");
+    }
+    if app.task_panel.iter().any(|task| task.status == "running") {
+        blockers.push("background tasks are running");
+    }
+    blockers
+}
+
 /// Load session from file
 pub fn load(app: &mut App, path: Option<&str>) -> CommandResult {
     let load_path = if let Some(p) = path {
@@ -169,11 +236,13 @@ pub fn load(app: &mut App, path: Option<&str>) -> CommandResult {
     app.extend_history(cells_to_add);
     app.mark_history_updated();
     app.viewport.transcript_selection.clear();
-    app.model.clone_from(&session.metadata.model);
+    app.set_model_selection(session.metadata.model.clone());
     app.update_model_compaction_budget();
     app.workspace.clone_from(&session.metadata.workspace);
     app.session.total_tokens = u32::try_from(session.metadata.total_tokens).unwrap_or(u32::MAX);
     app.session.total_conversation_tokens = app.session.total_tokens;
+    // Accumulated token breakdown is per-runtime-session; zero on load.
+    app.session.reset_token_breakdown();
     app.session.session_cost = 0.0;
     app.session.session_cost_cny = 0.0;
     app.session.subagent_cost = 0.0;
@@ -220,6 +289,14 @@ pub fn compact(_app: &mut App) -> CommandResult {
     )
 }
 
+/// Trigger agent-driven context purging.
+pub fn purge(_app: &mut App) -> CommandResult {
+    CommandResult::with_message_and_action(
+        "Agent context purge triggered...".to_string(),
+        AppAction::PurgeContext,
+    )
+}
+
 /// Export conversation to markdown
 pub fn export(app: &mut App, path: Option<&str>) -> CommandResult {
     let export_path = path.map_or_else(
@@ -363,8 +440,8 @@ fn line_to_string(line: ratatui::text::Line<'static>) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::config::Config;
-    use crate::tui::app::{App, TuiOptions, TurnCacheRecord};
+    use crate::config::{Config, DEFAULT_TEXT_MODEL};
+    use crate::tui::app::{App, ReasoningEffort, TuiOptions, TurnCacheRecord};
     use std::time::Instant;
     use tempfile::TempDir;
 
@@ -485,22 +562,140 @@ mod tests {
     }
 
     #[test]
-    fn test_save_with_default_path_uses_workspace() {
+    fn new_session_from_resumed_state_creates_distinct_empty_session() {
         let tmpdir = TempDir::new().unwrap();
         let mut app = create_test_app_with_tmpdir(&tmpdir);
+        app.current_session_id = Some("old-session".to_string());
+        app.session_title = Some("Old Session".to_string());
+        app.api_messages.push(crate::models::Message {
+            role: "user".to_string(),
+            content: vec![crate::models::ContentBlock::Text {
+                text: "continue this thread".to_string(),
+                cache_control: None,
+            }],
+        });
+        app.add_message(HistoryCell::System {
+            content: "old transcript".to_string(),
+        });
+        app.system_prompt = Some(crate::models::SystemPrompt::Text("old prompt".to_string()));
+        app.session.total_tokens = 123;
+        app.session.session_cost = 1.25;
+
+        let result = new_session(&mut app, None);
+
+        assert!(!result.is_error, "{:?}", result.message);
+        let new_id = app.current_session_id.clone().expect("new session id");
+        assert_ne!(new_id, "old-session");
+        assert_eq!(app.session_title.as_deref(), Some("New Session"));
+        assert!(app.api_messages.is_empty());
+        assert!(app.history.is_empty());
+        assert!(app.system_prompt.is_none());
+        assert_eq!(app.session.total_tokens, 0);
+        assert_eq!(app.session.session_cost, 0.0);
+        assert!(
+            result
+                .message
+                .as_deref()
+                .unwrap_or_default()
+                .contains("/resume")
+        );
+        match result.action {
+            Some(AppAction::SyncSession {
+                session_id,
+                messages,
+                system_prompt,
+                ..
+            }) => {
+                assert_eq!(session_id.as_deref(), Some(new_id.as_str()));
+                assert!(messages.is_empty());
+                assert!(system_prompt.is_none());
+            }
+            other => panic!("expected SyncSession action, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn new_session_blocks_unsent_input_without_force() {
+        let tmpdir = TempDir::new().unwrap();
+        let mut app = create_test_app_with_tmpdir(&tmpdir);
+        app.current_session_id = Some("old-session".to_string());
+        app.input = "draft text".to_string();
+
+        let result = new_session(&mut app, None);
+
+        assert!(result.is_error);
+        assert_eq!(app.current_session_id.as_deref(), Some("old-session"));
+        assert_eq!(app.input, "draft text");
+        assert!(result.action.is_none());
+        assert!(
+            result
+                .message
+                .as_deref()
+                .unwrap_or_default()
+                .contains("/new --force")
+        );
+    }
+
+    #[test]
+    fn new_session_force_discards_unsent_input() {
+        let tmpdir = TempDir::new().unwrap();
+        let mut app = create_test_app_with_tmpdir(&tmpdir);
+        app.current_session_id = Some("old-session".to_string());
+        app.input = "draft text".to_string();
+
+        let result = new_session(&mut app, Some("--force"));
+
+        assert!(!result.is_error, "{:?}", result.message);
+        assert_ne!(app.current_session_id.as_deref(), Some("old-session"));
+        assert!(app.input.is_empty());
+        assert!(matches!(result.action, Some(AppAction::SyncSession { .. })));
+    }
+
+    #[test]
+    fn new_session_blocks_in_flight_turn_without_force() {
+        let tmpdir = TempDir::new().unwrap();
+        let mut app = create_test_app_with_tmpdir(&tmpdir);
+        app.current_session_id = Some("old-session".to_string());
+        app.is_loading = true;
+
+        let result = new_session(&mut app, None);
+
+        assert!(result.is_error);
+        assert_eq!(app.current_session_id.as_deref(), Some("old-session"));
+        assert!(result.action.is_none());
+    }
+
+    #[test]
+    fn test_save_with_default_path_uses_managed_sessions_dir() {
+        let tmpdir = TempDir::new().unwrap();
+        // Set CODEWHALE_HOME so the managed sessions directory lands inside the
+        // temp dir rather than the real user home. Pre-create the directory so
+        // resolve_state_dir picks it up instead of falling back to legacy.
+        let home = tmpdir.path().join("home");
+        let sessions_dir = home.join("sessions");
+        std::fs::create_dir_all(&sessions_dir).unwrap();
+        // SAFETY: test-only, single-threaded via cargo test
+        unsafe { std::env::set_var("CODEWHALE_HOME", home.to_str().unwrap()) };
+        let mut app = create_test_app_with_tmpdir(&tmpdir);
         let result = save(&mut app, None);
         assert!(result.message.is_some());
         let msg = result.message.unwrap();
-        // Should create file in workspace with timestamp name
         // Give it a moment to ensure file is written
         std::thread::sleep(std::time::Duration::from_millis(10));
-        let entries: Vec<_> = std::fs::read_dir(tmpdir.path())
-            .unwrap()
-            .filter_map(|e| e.ok())
-            .filter(|e| e.file_name().to_string_lossy().starts_with("session_"))
-            .collect();
-        // Test passes if file was created or if save returned success message
-        assert!(!entries.is_empty() || msg.contains("Session saved"));
+        let entries: Vec<_> = if sessions_dir.exists() {
+            std::fs::read_dir(&sessions_dir)
+                .unwrap()
+                .filter_map(|e| e.ok())
+                .filter(|e| e.file_name().to_string_lossy().starts_with("session_"))
+                .collect()
+        } else {
+            Vec::new()
+        };
+        // Session should be saved to the managed dir, not the workspace root.
+        assert!(
+            !entries.is_empty(),
+            "expected session file in {sessions_dir:?}, got none; msg: {msg}"
+        );
     }
 
     #[test]
@@ -573,6 +768,31 @@ mod tests {
         assert!(matches!(result.action, Some(AppAction::SyncSession { .. })));
     }
 
+    #[test]
+    fn load_auto_model_session_restores_auto_mode() {
+        let tmpdir = TempDir::new().unwrap();
+        let mut saved_app = create_test_app_with_tmpdir(&tmpdir);
+        saved_app.set_model_selection("auto".to_string());
+        saved_app.last_effective_model = Some("deepseek-v4-flash".to_string());
+        saved_app.last_effective_reasoning_effort = Some(ReasoningEffort::Low);
+        let save_path = tmpdir.path().join("auto_model.json");
+        save(&mut saved_app, Some(save_path.to_str().unwrap()));
+
+        let mut app = create_test_app_with_tmpdir(&tmpdir);
+        app.set_model_selection("deepseek-v4-flash".to_string());
+        app.reasoning_effort = ReasoningEffort::High;
+        let result = load(&mut app, Some(save_path.to_str().unwrap()));
+
+        assert!(!result.is_error);
+        assert!(app.auto_model);
+        assert_eq!(app.model, "auto");
+        assert_eq!(app.model_selection_for_persistence(), "auto");
+        assert_eq!(app.last_effective_model, None);
+        assert_eq!(app.last_effective_reasoning_effort, None);
+        assert_eq!(app.reasoning_effort, ReasoningEffort::Auto);
+        assert_eq!(app.effective_model_for_budget(), DEFAULT_TEXT_MODEL);
+    }
+
     #[test]
     fn load_restores_artifact_registry() {
         let tmpdir = TempDir::new().unwrap();
diff --git a/crates/tui/src/commands/skills.rs b/crates/tui/src/commands/skills.rs
index b1823d5f..a8a4997f 100644
--- a/crates/tui/src/commands/skills.rs
+++ b/crates/tui/src/commands/skills.rs
@@ -441,7 +441,7 @@ fn sync_skills(app: &mut App) -> CommandResult {
                     }
                     SkillSyncOutcome::Denied { name, host } => {
                         failed += 1;
-                        let _ = writeln!(out, "  [x] {name} — network denied ({host})");
+                        let _ = writeln!(out, "  [!] {name} — network denied ({host})");
                     }
                     SkillSyncOutcome::NeedsApproval { name, host } => {
                         failed += 1;
diff --git a/crates/tui/src/commands/status.rs b/crates/tui/src/commands/status.rs
index c721dec7..fb1a7e6d 100644
--- a/crates/tui/src/commands/status.rs
+++ b/crates/tui/src/commands/status.rs
@@ -64,6 +64,26 @@ fn format_status(app: &App) -> String {
         &token_count(app.session.last_completion_tokens),
     );
     push_row(&mut out, "Cache hit/miss:", &cache_summary(app));
+    push_row(
+        &mut out,
+        "Session input:",
+        &app.session.total_input_tokens.to_string(),
+    );
+    let session_cache =
+        if app.session.total_cache_hit_tokens == 0 && app.session.total_cache_miss_tokens == 0 {
+            "not reported".to_string()
+        } else {
+            format!(
+                "{} hit / {} miss",
+                app.session.total_cache_hit_tokens, app.session.total_cache_miss_tokens
+            )
+        };
+    push_row(&mut out, "Session cache:", &session_cache);
+    push_row(
+        &mut out,
+        "Session output:",
+        &app.session.total_output_tokens.to_string(),
+    );
     push_row(
         &mut out,
         "Total tokens:",
@@ -83,6 +103,13 @@ fn format_status(app: &App) -> String {
             app.api_messages.len()
         ),
     );
+    let tool_output_status =
+        crate::tool_output_receipts::tool_output_status(&app.api_messages, &app.session_artifacts);
+    push_row(
+        &mut out,
+        "Tool outputs:",
+        &crate::tool_output_receipts::format_tool_output_status(&tool_output_status),
+    );
     push_row(
         &mut out,
         "Rate limits:",
@@ -237,11 +264,48 @@ mod tests {
         assert!(msg.contains("Session:"));
         assert!(msg.contains("session-123"));
         assert!(msg.contains("Context window:"));
+        assert!(msg.contains("Tool outputs:"));
         assert!(msg.contains("Cache hit/miss:"));
         assert!(msg.contains("70 hit / 30 miss"));
         assert!(msg.contains("Use /statusline to configure footer items."));
     }
 
+    #[test]
+    fn status_report_surfaces_large_tool_output_pressure() {
+        let tmpdir = TempDir::new().expect("temp dir");
+        let mut app = create_test_app(tmpdir.path().to_path_buf());
+        let raw = "RAW_STATUS_PRESSURE\n".repeat(2_000);
+        app.api_messages.push(Message {
+            role: "user".to_string(),
+            content: vec![ContentBlock::ToolResult {
+                tool_use_id: "call-big".to_string(),
+                content: raw,
+                is_error: None,
+                content_blocks: None,
+            }],
+        });
+        app.session_artifacts
+            .push(crate::artifacts::ArtifactRecord {
+                id: "art_call-big".to_string(),
+                kind: crate::artifacts::ArtifactKind::ToolOutput,
+                session_id: "session-123".to_string(),
+                tool_call_id: "call-big".to_string(),
+                tool_name: "exec_shell".to_string(),
+                created_at: chrono::Utc::now(),
+                byte_size: 24_000,
+                preview: "large output".to_string(),
+                storage_path: PathBuf::from("artifacts/art_call-big.txt"),
+            });
+
+        let result = status(&mut app);
+        let msg = result.message.expect("status message");
+
+        assert!(msg.contains("Tool outputs:"));
+        assert!(msg.contains("raw over cap"));
+        assert!(msg.contains("context pressure"));
+        assert!(msg.contains("artifact"));
+    }
+
     #[test]
     fn project_docs_reports_missing_docs() {
         let tmpdir = TempDir::new().expect("temp dir");
diff --git a/crates/tui/src/commands/user_commands.rs b/crates/tui/src/commands/user_commands.rs
index d4290757..48260bfe 100644
--- a/crates/tui/src/commands/user_commands.rs
+++ b/crates/tui/src/commands/user_commands.rs
@@ -5,6 +5,10 @@
 //! (without `.md` extension) becomes a slash command. When invoked via
 //! `/name`, the file contents are sent as a user message.
 //!
+//! Files may include optional YAML-like frontmatter between `---` markers.
+//! Supported fields are `description`, `argument-hint`, and `allowed-tools`.
+//! Frontmatter is stripped before the command body is sent to the model.
+//!
 //! ## Precedence
 //!
 //! Workspace-local directories shadow user-global by name:
@@ -17,7 +21,7 @@
 use std::collections::HashSet;
 use std::path::{Path, PathBuf};
 
-use crate::tui::app::{App, AppAction};
+use crate::tui::app::{App, AppAction, HuntVerdict};
 
 use super::CommandResult;
 
@@ -95,6 +99,72 @@ pub fn load_user_commands(workspace: Option<&Path>) -> Vec<(String, String)> {
     commands
 }
 
+pub(crate) fn parse_frontmatter(content: &str) -> (Vec<(String, String)>, &str) {
+    let Some(first_line_end) = content.find('\n') else {
+        return (Vec::new(), content);
+    };
+    let first = content[..first_line_end].trim_end_matches('\r');
+
+    if first.trim().chars().all(|ch| ch == '-') && first.trim().len() >= 3 {
+        let mut metadata = Vec::new();
+        let mut offset = first_line_end + 1;
+        let mut unclosed_body_start = None;
+        for raw_line in content[offset..].split_inclusive('\n') {
+            let line_start = offset;
+            let line = raw_line.trim_end_matches(['\r', '\n']);
+            offset += raw_line.len();
+            let trimmed = line.trim();
+            if unclosed_body_start.is_none() {
+                if trimmed.chars().all(|ch| ch == '-') && trimmed.len() >= 3 {
+                    let body = content[offset..].trim_start_matches(['\r', '\n']);
+                    return (metadata, body);
+                }
+                if let Some((key, value)) = line.split_once(':') {
+                    let key = key.trim().to_ascii_lowercase();
+                    let raw_value = value.trim();
+                    let value = if key == "allowed-tools" {
+                        raw_value.to_string()
+                    } else {
+                        strip_matched_quotes(raw_value).to_string()
+                    };
+                    if !key.is_empty() {
+                        metadata.push((key, value));
+                    }
+                } else if !trimmed.is_empty() {
+                    unclosed_body_start = Some(line_start);
+                }
+            }
+        }
+        let body_start = unclosed_body_start.unwrap_or(content.len());
+        let body = content[body_start..].trim_start_matches(['\r', '\n']);
+        return (metadata, body);
+    }
+
+    (Vec::new(), content)
+}
+
+fn strip_matched_quotes(value: &str) -> &str {
+    if let Some(stripped) = value.strip_prefix('"').and_then(|v| v.strip_suffix('"')) {
+        return stripped;
+    }
+    if let Some(stripped) = value.strip_prefix('\'').and_then(|v| v.strip_suffix('\'')) {
+        return stripped;
+    }
+    value
+}
+
+fn parse_allowed_tools(value: &str) -> Vec<String> {
+    value
+        .split(',')
+        .map(|tool| {
+            strip_matched_quotes(tool.trim())
+                .trim()
+                .to_ascii_lowercase()
+        })
+        .filter(|tool| !tool.is_empty())
+        .collect()
+}
+
 /// Check if the input matches a user-defined command and return the
 /// content as a `SendMessage` action.
 ///
@@ -121,7 +191,25 @@ pub fn try_dispatch_user_command(app: &mut App, input: &str) -> Option<CommandRe
 
     for (name, content) in &user_commands {
         if name == command {
-            let message = apply_template(content, args);
+            let (metadata, body) = parse_frontmatter(content);
+            app.hunt.quarry = None;
+            app.hunt.started_at = None;
+            app.hunt.verdict = HuntVerdict::Hunting;
+            app.hunt.token_budget = None;
+            app.active_allowed_tools = None;
+            for (key, value) in &metadata {
+                match key.as_str() {
+                    "description" => {
+                        app.hunt.quarry = Some(value.clone());
+                        app.hunt.started_at = Some(std::time::Instant::now());
+                    }
+                    "allowed-tools" => {
+                        app.active_allowed_tools = Some(parse_allowed_tools(value));
+                    }
+                    _ => {}
+                }
+            }
+            let message = apply_template(body, args);
             return Some(CommandResult::action(AppAction::SendMessage(message)));
         }
     }
@@ -217,6 +305,30 @@ mod tests {
         std::fs::write(dir.join(format!("{name}.md")), body).unwrap();
     }
 
+    fn test_options(workspace: PathBuf) -> crate::tui::app::TuiOptions {
+        crate::tui::app::TuiOptions {
+            model: "deepseek-v4-pro".to_string(),
+            workspace,
+            config_path: None,
+            config_profile: None,
+            allow_shell: false,
+            use_alt_screen: true,
+            use_mouse_capture: false,
+            use_bracketed_paste: true,
+            max_subagents: 1,
+            skills_dir: PathBuf::from("."),
+            memory_path: PathBuf::from("memory.md"),
+            notes_path: PathBuf::from("notes.txt"),
+            mcp_config_path: PathBuf::from("mcp.json"),
+            use_memory: false,
+            start_in_agent_mode: false,
+            skip_onboarding: true,
+            yolo: false,
+            resume_session_id: None,
+            initial_input: None,
+        }
+    }
+
     #[test]
     fn load_user_commands_scans_workspace_local_dir() {
         let tmp = TempDir::new().unwrap();
@@ -363,4 +475,180 @@ mod tests {
             "got: {matches:?}"
         );
     }
+
+    #[test]
+    fn frontmatter_is_stripped_before_dispatch() {
+        use crate::config::Config;
+
+        let tmp = TempDir::new().unwrap();
+        let ws = tmp.path().to_path_buf();
+        write_command(
+            &ws.join(".deepseek").join("commands"),
+            "secure",
+            "---\ndescription: Secure scan\nallowed-tools: Bash, Read\n---\nRun $ARGUMENTS",
+        );
+
+        let mut app = App::new(test_options(ws), &Config::default());
+        let result = try_dispatch_user_command(&mut app, "/secure checks").unwrap();
+        match result.action {
+            Some(AppAction::SendMessage(msg)) => assert_eq!(msg, "Run checks"),
+            other => panic!("expected SendMessage action, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn review_regression_unclosed_frontmatter_keeps_metadata_and_strips_header() {
+        let (metadata, body) = parse_frontmatter(
+            "---\ndescription: Broken command\nallowed-tools: Bash\nRun the safe body",
+        );
+
+        assert_eq!(
+            metadata,
+            vec![
+                ("description".to_string(), "Broken command".to_string()),
+                ("allowed-tools".to_string(), "Bash".to_string())
+            ]
+        );
+        assert_eq!(body, "Run the safe body");
+    }
+
+    #[test]
+    fn review_regression_unclosed_frontmatter_without_metadata_strips_header() {
+        let (metadata, body) =
+            parse_frontmatter("---\nRun the command body without a closing delimiter");
+
+        assert!(metadata.is_empty());
+        assert_eq!(body, "Run the command body without a closing delimiter");
+    }
+
+    #[test]
+    fn review_regression_frontmatter_strips_only_matched_quote_pairs() {
+        let (metadata, body) = parse_frontmatter("---\ndescription: 'Read\"\n---\nrun");
+
+        assert_eq!(
+            metadata,
+            vec![("description".to_string(), "'Read\"".to_string())]
+        );
+        assert_eq!(body, "run");
+    }
+
+    #[test]
+    fn allowed_tools_frontmatter_sets_app_state() {
+        use crate::config::Config;
+
+        let tmp = TempDir::new().unwrap();
+        let ws = tmp.path().to_path_buf();
+        write_command(
+            &ws.join(".deepseek").join("commands"),
+            "secure",
+            "---\nallowed-tools: Bash, Grep\n---\nrun tests",
+        );
+
+        let mut app = App::new(test_options(ws), &Config::default());
+        let _ = try_dispatch_user_command(&mut app, "/secure").unwrap();
+        assert_eq!(
+            app.active_allowed_tools,
+            Some(vec!["bash".to_string(), "grep".to_string()])
+        );
+    }
+
+    #[test]
+    fn review_regression_empty_allowed_tools_blocks_all_tools() {
+        use crate::config::Config;
+
+        let tmp = TempDir::new().unwrap();
+        let ws = tmp.path().to_path_buf();
+        write_command(
+            &ws.join(".deepseek").join("commands"),
+            "locked",
+            "---\nallowed-tools: \"\"\n---\nrun nothing",
+        );
+
+        let mut app = App::new(test_options(ws), &Config::default());
+        let _ = try_dispatch_user_command(&mut app, "/locked").unwrap();
+        assert_eq!(app.active_allowed_tools, Some(Vec::new()));
+    }
+
+    #[test]
+    fn review_regression_allowed_tools_accepts_per_item_quotes() {
+        use crate::config::Config;
+
+        let tmp = TempDir::new().unwrap();
+        let ws = tmp.path().to_path_buf();
+        write_command(
+            &ws.join(".deepseek").join("commands"),
+            "quoted",
+            "---\nallowed-tools: \"exec_shell\", 'read_file'\n---\nrun quoted tools",
+        );
+
+        let mut app = App::new(test_options(ws), &Config::default());
+        let _ = try_dispatch_user_command(&mut app, "/quoted").unwrap();
+        assert_eq!(
+            app.active_allowed_tools,
+            Some(vec!["exec_shell".to_string(), "read_file".to_string()])
+        );
+    }
+
+    #[test]
+    fn review_regression_dispatch_without_frontmatter_resets_previous_command_state() {
+        use crate::config::Config;
+
+        let tmp = TempDir::new().unwrap();
+        let ws = tmp.path().to_path_buf();
+        let commands_dir = ws.join(".deepseek").join("commands");
+        write_command(
+            &commands_dir,
+            "described",
+            "---\ndescription: Scan repos\nallowed-tools: Bash\n---\nscan",
+        );
+        write_command(&commands_dir, "plain", "plain command");
+
+        let mut app = App::new(test_options(ws), &Config::default());
+        let _ = try_dispatch_user_command(&mut app, "/described").unwrap();
+        assert_eq!(app.hunt.quarry.as_deref(), Some("Scan repos"));
+        assert!(app.hunt.started_at.is_some());
+        assert_eq!(app.hunt.verdict, crate::tui::app::HuntVerdict::Hunting);
+        assert_eq!(app.hunt.token_budget, None);
+        assert_eq!(app.active_allowed_tools, Some(vec!["bash".to_string()]));
+
+        app.hunt.verdict = crate::tui::app::HuntVerdict::Escaped;
+        app.hunt.token_budget = Some(42);
+        let _ = try_dispatch_user_command(&mut app, "/plain").unwrap();
+        assert_eq!(app.hunt.quarry, None);
+        assert_eq!(app.hunt.started_at, None);
+        assert_eq!(app.hunt.verdict, crate::tui::app::HuntVerdict::Hunting);
+        assert_eq!(app.hunt.token_budget, None);
+        assert_eq!(app.active_allowed_tools, None);
+    }
+
+    #[test]
+    fn description_frontmatter_sets_work_objective_and_autocomplete_description() {
+        use crate::config::Config;
+
+        let tmp = TempDir::new().unwrap();
+        let ws = tmp.path().to_path_buf();
+        write_command(
+            &ws.join(".deepseek").join("commands"),
+            "git-scan",
+            "---\ndescription: Scan nested git repositories\nargument-hint: <root>\n---\nscan",
+        );
+
+        let mut app = App::new(test_options(ws.clone()), &Config::default());
+        let _ = try_dispatch_user_command(&mut app, "/git-scan").unwrap();
+        assert_eq!(
+            app.hunt.quarry.as_deref(),
+            Some("Scan nested git repositories")
+        );
+        let commands = load_user_commands(Some(&ws));
+        let (_, content) = commands
+            .iter()
+            .find(|(name, _)| name == "git-scan")
+            .expect("git-scan command should load");
+        let (metadata, _) = parse_frontmatter(content);
+        assert!(metadata.contains(&(
+            "description".to_string(),
+            "Scan nested git repositories".to_string()
+        )));
+        assert!(metadata.contains(&("argument-hint".to_string(), "<root>".to_string())));
+    }
 }
diff --git a/crates/tui/src/compaction.rs b/crates/tui/src/compaction.rs
index 460eb9e0..4048524d 100644
--- a/crates/tui/src/compaction.rs
+++ b/crates/tui/src/compaction.rs
@@ -1032,7 +1032,13 @@ fn read_workspace_anchors(workspace: Option<&Path>) -> Vec<String> {
         return Vec::new();
     };
 
-    let anchors_path = ws.join(".deepseek").join("anchors.md");
+    // Prefer .codewhale, fall back to .deepseek
+    let primary = ws.join(".codewhale").join("anchors.md");
+    let anchors_path = if primary.exists() {
+        primary
+    } else {
+        ws.join(".deepseek").join("anchors.md")
+    };
     let Ok(content) = std::fs::read_to_string(anchors_path) else {
         return Vec::new();
     };
diff --git a/crates/tui/src/composer_history.rs b/crates/tui/src/composer_history.rs
index 4f8bb1ce..92e99328 100644
--- a/crates/tui/src/composer_history.rs
+++ b/crates/tui/src/composer_history.rs
@@ -79,29 +79,44 @@ pub fn append_history(entry: &str) {
 /// write if the channel send fails) so callers never block on disk I/O.
 fn append_history_dispatched(path: &Path, entry: &str) {
     let entry = entry.to_string();
-    if writer_sender()
-        .send((path.to_path_buf(), entry.clone()))
-        .is_err()
-    {
-        append_history_to(path, &entry);
+    if let Err(err) = writer_sender().send(HistoryWrite::Append(path.to_path_buf(), entry)) {
+        match err.0 {
+            HistoryWrite::Append(path, entry) => append_history_to(&path, &entry),
+            #[cfg(test)]
+            HistoryWrite::Flush(_) => unreachable!("flush messages are only sent by tests"),
+        }
     }
 }
 
+enum HistoryWrite {
+    Append(PathBuf, String),
+    #[cfg(test)]
+    Flush(Sender<()>),
+}
+
 /// Lazy singleton sender for the dedicated composer-history writer
 /// thread. Initialised on first use; the thread runs for the lifetime
 /// of the process and drains queued writes in arrival order.
-fn writer_sender() -> &'static Sender<(PathBuf, String)> {
-    static SENDER: OnceLock<Sender<(PathBuf, String)>> = OnceLock::new();
+fn writer_sender() -> &'static Sender<HistoryWrite> {
+    static SENDER: OnceLock<Sender<HistoryWrite>> = OnceLock::new();
     SENDER.get_or_init(|| {
-        let (tx, rx) = channel::<(PathBuf, String)>();
+        let (tx, rx) = channel::<HistoryWrite>();
         let spawn_result = std::thread::Builder::new()
             .name("composer-history-writer".to_string())
             .spawn(move || {
                 // recv() returns Err when all senders have dropped, which
                 // only happens at process shutdown because the singleton
                 // sender lives in a static for the lifetime of the process.
-                while let Ok(first) = rx.recv() {
-                    append_history_batch(&rx, first);
+                while let Ok(message) = rx.recv() {
+                    match message {
+                        HistoryWrite::Append(path, entry) => {
+                            append_history_batch(&rx, (path, entry));
+                        }
+                        #[cfg(test)]
+                        HistoryWrite::Flush(done) => {
+                            let _ = done.send(());
+                        }
+                    }
                 }
             });
         if let Err(err) = spawn_result {
@@ -111,12 +126,19 @@ fn writer_sender() -> &'static Sender<(PathBuf, String)> {
     })
 }
 
-fn append_history_batch(rx: &Receiver<(PathBuf, String)>, first: (PathBuf, String)) {
+fn append_history_batch(rx: &Receiver<HistoryWrite>, first: (PathBuf, String)) {
     let mut pending = vec![first];
+    #[cfg(test)]
+    let mut flush = None;
 
     loop {
         match rx.recv_timeout(Duration::from_millis(2)) {
-            Ok(next) => pending.push(next),
+            Ok(HistoryWrite::Append(path, entry)) => pending.push((path, entry)),
+            #[cfg(test)]
+            Ok(HistoryWrite::Flush(done)) => {
+                flush = Some(done);
+                break;
+            }
             Err(RecvTimeoutError::Timeout) => break,
             Err(RecvTimeoutError::Disconnected) => break,
         }
@@ -125,6 +147,11 @@ fn append_history_batch(rx: &Receiver<(PathBuf, String)>, first: (PathBuf, Strin
     for (path, entries) in group_history_writes_by_path(pending) {
         append_history_entries_to(&path, entries.iter().map(String::as_str));
     }
+
+    #[cfg(test)]
+    if let Some(done) = flush {
+        let _ = done.send(());
+    }
 }
 
 fn group_history_writes_by_path(writes: Vec<(PathBuf, String)>) -> Vec<(PathBuf, Vec<String>)> {
@@ -190,7 +217,7 @@ fn append_history_entries_to<'a>(
     }
 
     let payload = entries.join("\n") + "\n";
-    if let Err(err) = crate::utils::write_atomic(path, payload.as_bytes()) {
+    if let Err(err) = write_history_atomic(path, payload.as_bytes()) {
         tracing::warn!(
             "Failed to persist composer history at {}: {err}",
             path.display()
@@ -198,9 +225,44 @@ fn append_history_entries_to<'a>(
     }
 }
 
+fn write_history_atomic(path: &Path, payload: &[u8]) -> std::io::Result<()> {
+    const RETRY_DELAYS: &[Duration] = &[
+        Duration::from_millis(5),
+        Duration::from_millis(10),
+        Duration::from_millis(25),
+        Duration::from_millis(50),
+        Duration::from_millis(100),
+        Duration::from_millis(200),
+        Duration::from_millis(400),
+    ];
+
+    for (attempt, delay) in RETRY_DELAYS
+        .iter()
+        .map(Some)
+        .chain(std::iter::once(None))
+        .enumerate()
+    {
+        match crate::utils::write_atomic(path, payload) {
+            Ok(()) => return Ok(()),
+            Err(err) if delay.is_some() => {
+                tracing::debug!(
+                    "Retrying composer history write to {} after attempt {} failed: {err}",
+                    path.display(),
+                    attempt + 1
+                );
+                std::thread::sleep(*delay.expect("delay checked"));
+            }
+            Err(err) => return Err(err),
+        }
+    }
+
+    unreachable!("retry iterator always ends with a final write attempt")
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::time::{Duration, Instant};
 
     /// Tests use the path-injecting `*_from` / `*_to` helpers so they
     /// don't have to mutate `HOME` (which is not honored by
@@ -213,6 +275,16 @@ mod tests {
         (tmp, path)
     }
 
+    fn flush_history_writer_for_tests(timeout: Duration) {
+        let (done_tx, done_rx) = channel();
+        writer_sender()
+            .send(HistoryWrite::Flush(done_tx))
+            .expect("history writer accepts flush");
+        done_rx
+            .recv_timeout(timeout)
+            .expect("history writer flush timed out");
+    }
+
     #[test]
     fn append_and_load_round_trip() {
         let (_tmp, path) = temp_history_path();
@@ -283,8 +355,6 @@ mod tests {
     /// stall the user reports.
     #[test]
     fn append_history_dispatched_does_not_block_the_caller() {
-        use std::time::{Duration, Instant};
-
         let (_tmp, path) = temp_history_path();
         // Seed close to the cap so a synchronous rewrite is non-trivial.
         let seed = (0..(MAX_HISTORY_ENTRIES - 50))
@@ -311,26 +381,16 @@ mod tests {
              (likely re-introduced #1927: caller blocked on disk write)"
         );
 
-        // Give the writer thread time to drain the queue, then verify the
-        // new entries landed.
-        // Use 10s on Windows (slow CI I/O) vs 5s on other platforms.
-        let deadline = Instant::now() + Duration::from_secs(if cfg!(windows) { 10 } else { 5 });
-        loop {
-            let loaded = load_history_from(&path);
-            if loaded.iter().any(|line| line == "new entry 49") {
-                // Last dispatched entry observed; queue is drained.
-                assert!(loaded.iter().any(|line| line == "new entry 0"));
-                break;
-            }
-            if Instant::now() >= deadline {
-                panic!(
-                    "writer thread did not persist the dispatched entries; \
-                     loaded {} entries, last = {:?}",
-                    loaded.len(),
-                    loaded.last()
-                );
-            }
-            std::thread::sleep(Duration::from_millis(25));
-        }
+        flush_history_writer_for_tests(Duration::from_secs(if cfg!(windows) { 10 } else { 5 }));
+
+        let loaded = load_history_from(&path);
+        assert!(
+            loaded.iter().any(|line| line == "new entry 49"),
+            "writer thread did not persist the dispatched entries; \
+             loaded {} entries, last = {:?}",
+            loaded.len(),
+            loaded.last()
+        );
+        assert!(loaded.iter().any(|line| line == "new entry 0"));
     }
 }
diff --git a/crates/tui/src/config.rs b/crates/tui/src/config.rs
index b4171255..864ede1d 100644
--- a/crates/tui/src/config.rs
+++ b/crates/tui/src/config.rs
@@ -6,6 +6,7 @@ use std::fs;
 #[cfg(unix)]
 use std::io::Write as _;
 use std::path::{Path, PathBuf};
+use std::time::Duration;
 
 use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
@@ -36,20 +37,29 @@ pub const DEFAULT_DEEPSEEK_BASE_URL: &str = "https://api.deepseek.com/beta";
 pub const DEFAULT_NVIDIA_NIM_MODEL: &str = "deepseek-ai/deepseek-v4-pro";
 pub const DEFAULT_NVIDIA_NIM_FLASH_MODEL: &str = "deepseek-ai/deepseek-v4-flash";
 pub const DEFAULT_NVIDIA_NIM_BASE_URL: &str = "https://integrate.api.nvidia.com/v1";
-pub const DEFAULT_OPENAI_MODEL: &str = "gpt-4.1";
+pub const DEFAULT_OPENAI_MODEL: &str = "deepseek-v4-pro";
 pub const DEFAULT_OPENAI_BASE_URL: &str = "https://api.openai.com/v1";
 pub const DEFAULT_ATLASCLOUD_MODEL: &str = "deepseek-ai/deepseek-v4-flash";
 pub const DEFAULT_ATLASCLOUD_BASE_URL: &str = "https://api.atlascloud.ai/v1";
 pub const DEFAULT_WANJIE_ARK_MODEL: &str = "deepseek-reasoner";
+pub const DEFAULT_VOLCENGINE_MODEL: &str = "DeepSeek-V4-Pro";
+pub const DEFAULT_VOLCENGINE_FLASH_MODEL: &str = "DeepSeek-V4-Flash";
+pub const DEFAULT_VOLCENGINE_BASE_URL: &str = "https://ark.cn-beijing.volces.com/api/coding/v3";
 pub const DEFAULT_WANJIE_ARK_BASE_URL: &str = "https://maas-openapi.wanjiedata.com/api/v1";
 pub const DEFAULT_OPENROUTER_MODEL: &str = "deepseek/deepseek-v4-pro";
 pub const DEFAULT_OPENROUTER_FLASH_MODEL: &str = "deepseek/deepseek-v4-flash";
 pub const DEFAULT_OPENROUTER_BASE_URL: &str = "https://openrouter.ai/api/v1";
+pub const DEFAULT_XIAOMI_MIMO_MODEL: &str = "mimo-v2.5-pro";
+pub const DEFAULT_XIAOMI_MIMO_BASE_URL: &str = "https://api.xiaomimimo.com/v1";
 pub const DEFAULT_NOVITA_MODEL: &str = "deepseek/deepseek-v4-pro";
 pub const DEFAULT_NOVITA_FLASH_MODEL: &str = "deepseek/deepseek-v4-flash";
 pub const DEFAULT_NOVITA_BASE_URL: &str = "https://api.novita.ai/v1";
 pub const DEFAULT_FIREWORKS_MODEL: &str = "accounts/fireworks/models/deepseek-v4-pro";
 pub const DEFAULT_FIREWORKS_BASE_URL: &str = "https://api.fireworks.ai/inference/v1";
+pub const DEFAULT_MOONSHOT_MODEL: &str = "kimi-k2.6";
+pub const DEFAULT_MOONSHOT_BASE_URL: &str = "https://api.moonshot.ai/v1";
+pub const DEFAULT_KIMI_CODE_MODEL: &str = "kimi-for-coding";
+pub const DEFAULT_KIMI_CODE_BASE_URL: &str = "https://api.kimi.com/coding/v1";
 pub const DEFAULT_SGLANG_MODEL: &str = "deepseek-ai/DeepSeek-V4-Pro";
 pub const DEFAULT_SGLANG_FLASH_MODEL: &str = "deepseek-ai/DeepSeek-V4-Flash";
 pub const DEFAULT_SGLANG_BASE_URL: &str = "http://localhost:30000/v1";
@@ -85,9 +95,12 @@ pub enum ApiProvider {
     Openai,
     Atlascloud,
     WanjieArk,
+    Volcengine,
     Openrouter,
+    XiaomiMimo,
     Novita,
     Fireworks,
+    Moonshot,
     Sglang,
     Vllm,
     Ollama,
@@ -106,9 +119,15 @@ impl ApiProvider {
             "atlascloud" | "atlas-cloud" | "atlas_cloud" | "atlas" => Some(Self::Atlascloud),
             "wanjie" | "wanjie-ark" | "wanjie_ark" | "ark-wanjie" | "ark_wanjie" | "wanjieark"
             | "wanjie-maas" | "wanjie_maas" | "wanjiemaas" => Some(Self::WanjieArk),
+            "volcengine" | "volcengine-ark" | "volcengine_ark" | "ark" | "volc-ark"
+            | "volcengineark" => Some(Self::Volcengine),
             "openrouter" | "open_router" => Some(Self::Openrouter),
+            "xiaomi-mimo" | "xiaomi_mimo" | "xiaomimimo" | "mimo" | "xiaomi" => {
+                Some(Self::XiaomiMimo)
+            }
             "novita" => Some(Self::Novita),
             "fireworks" | "fireworks-ai" => Some(Self::Fireworks),
+            "moonshot" | "moonshot-ai" | "kimi" | "kimi-k2" => Some(Self::Moonshot),
             "sglang" | "sg-lang" => Some(Self::Sglang),
             "vllm" | "v-llm" => Some(Self::Vllm),
             "ollama" | "ollama-local" => Some(Self::Ollama),
@@ -125,9 +144,12 @@ impl ApiProvider {
             Self::Openai => "openai",
             Self::Atlascloud => "atlascloud",
             Self::WanjieArk => "wanjie-ark",
+            Self::Volcengine => "volcengine",
             Self::Openrouter => "openrouter",
+            Self::XiaomiMimo => "xiaomi-mimo",
             Self::Novita => "novita",
             Self::Fireworks => "fireworks",
+            Self::Moonshot => "moonshot",
             Self::Sglang => "sglang",
             Self::Vllm => "vllm",
             Self::Ollama => "ollama",
@@ -144,9 +166,12 @@ impl ApiProvider {
             Self::Openai => "OpenAI-compatible",
             Self::Atlascloud => "AtlasCloud",
             Self::WanjieArk => "Wanjie Ark",
+            Self::Volcengine => "Volcengine Ark",
             Self::Openrouter => "OpenRouter",
+            Self::XiaomiMimo => "Xiaomi MiMo",
             Self::Novita => "Novita AI",
             Self::Fireworks => "Fireworks AI",
+            Self::Moonshot => "Moonshot/Kimi",
             Self::Sglang => "SGLang",
             Self::Vllm => "vLLM",
             Self::Ollama => "Ollama",
@@ -162,9 +187,12 @@ impl ApiProvider {
             Self::Openai,
             Self::Atlascloud,
             Self::WanjieArk,
+            Self::Volcengine,
             Self::Openrouter,
+            Self::XiaomiMimo,
             Self::Novita,
             Self::Fireworks,
+            Self::Moonshot,
             Self::Sglang,
             Self::Vllm,
             Self::Ollama,
@@ -233,7 +261,10 @@ pub enum RequestPayloadMode {
 /// in the API payload (after normalization / provider-specific mapping).
 #[must_use]
 pub fn provider_capability(provider: ApiProvider, resolved_model: &str) -> ProviderCapability {
-    if matches!(provider, ApiProvider::Openai | ApiProvider::Atlascloud) {
+    if matches!(
+        provider,
+        ApiProvider::Openai | ApiProvider::Atlascloud | ApiProvider::Moonshot
+    ) {
         return ProviderCapability {
             provider,
             resolved_model: resolved_model.to_string(),
@@ -246,6 +277,19 @@ pub fn provider_capability(provider: ApiProvider, resolved_model: &str) -> Provi
         };
     }
 
+    if matches!(provider, ApiProvider::XiaomiMimo) {
+        return ProviderCapability {
+            provider,
+            resolved_model: resolved_model.to_string(),
+            context_window: 1_000_000,
+            max_output: 128_000,
+            thinking_supported: true,
+            cache_telemetry_supported: false,
+            request_payload_mode: RequestPayloadMode::ChatCompletions,
+            alias_deprecation: None,
+        };
+    }
+
     if matches!(provider, ApiProvider::Ollama) {
         return ProviderCapability {
             provider,
@@ -297,7 +341,10 @@ pub fn provider_capability(provider: ApiProvider, resolved_model: &str) -> Provi
     // Cache telemetry: returned only by DeepSeek-native and NVIDIA NIM endpoints.
     let cache_telemetry_supported = matches!(
         provider,
-        ApiProvider::Deepseek | ApiProvider::DeepseekCN | ApiProvider::NvidiaNim
+        ApiProvider::Deepseek
+            | ApiProvider::DeepseekCN
+            | ApiProvider::NvidiaNim
+            | ApiProvider::Volcengine
     );
 
     // Request payload mode: all current providers use chat completions.
@@ -398,12 +445,24 @@ fn canonical_official_deepseek_model_id(model: &str) -> Option<&'static str> {
 /// aliases are valid for some compatible backends, but sending them to
 /// DeepSeek's own API causes a 400. Keep the generic normalizer permissive for
 /// config/back-compat, and canonicalize only when the active provider is known.
+///
+/// Preserves the caller's casing when the model is already a recognised
+/// DeepSeek id (e.g. `DeepSeek-V4-Flash` stays as-is). Only rewrites compact
+/// aliases like `deepseek-v4pro` → `deepseek-v4-pro`.
 #[must_use]
 pub fn normalize_model_name_for_provider(provider: ApiProvider, model: &str) -> Option<String> {
     let normalized = normalize_model_name(model)?;
     if matches!(provider, ApiProvider::Deepseek | ApiProvider::DeepseekCN)
         && let Some(canonical) = canonical_official_deepseek_model_id(&normalized)
     {
+        // When the user's input already matches a known model id
+        // case-insensitively, keep their original casing; only rewrite
+        // compact aliases (e.g. v4pro → v4-pro).
+        if canonical.eq_ignore_ascii_case(&normalized)
+            || normalized.to_ascii_lowercase() == canonical
+        {
+            return Some(normalized);
+        }
         return Some(canonical.to_string());
     }
     if let Some(canonical) = canonical_official_deepseek_model_id(&normalized) {
@@ -418,11 +477,14 @@ pub fn model_completion_names_for_provider(provider: ApiProvider) -> Vec<&'stati
         ApiProvider::Deepseek | ApiProvider::DeepseekCN => OFFICIAL_DEEPSEEK_MODELS.to_vec(),
         ApiProvider::NvidiaNim => vec![DEFAULT_NVIDIA_NIM_MODEL, DEFAULT_NVIDIA_NIM_FLASH_MODEL],
         ApiProvider::Openrouter => vec![DEFAULT_OPENROUTER_MODEL, DEFAULT_OPENROUTER_FLASH_MODEL],
+        ApiProvider::XiaomiMimo => vec![DEFAULT_XIAOMI_MIMO_MODEL, "mimo-v2.5"],
         ApiProvider::Novita => vec![DEFAULT_NOVITA_MODEL, DEFAULT_NOVITA_FLASH_MODEL],
         ApiProvider::Fireworks => vec![DEFAULT_FIREWORKS_MODEL],
+        ApiProvider::Moonshot => vec![DEFAULT_MOONSHOT_MODEL],
         ApiProvider::WanjieArk => vec![DEFAULT_WANJIE_ARK_MODEL],
         ApiProvider::Sglang => vec![DEFAULT_SGLANG_MODEL, DEFAULT_SGLANG_FLASH_MODEL],
         ApiProvider::Vllm => vec![DEFAULT_VLLM_MODEL, DEFAULT_VLLM_FLASH_MODEL],
+        ApiProvider::Volcengine => vec![DEFAULT_VOLCENGINE_MODEL, DEFAULT_VOLCENGINE_FLASH_MODEL],
         ApiProvider::Openai | ApiProvider::Atlascloud | ApiProvider::Ollama => {
             OFFICIAL_DEEPSEEK_MODELS.to_vec()
         }
@@ -474,9 +536,9 @@ pub struct TuiConfig {
     /// - Unset (default) — fall back to the `[notifications]` defaults.
     pub notification_condition: Option<NotificationCondition>,
     /// When `true`, plain Up/Down on an empty composer scroll the
-    /// transcript instead of recalling input history.  Useful for
-    /// terminals that map trackpad gestures to arrow keys.  Default:
-    /// `false` (plain arrows always navigate input history, #1117).
+    /// transcript instead of recalling input history. Useful for
+    /// terminals that map mouse-wheel gestures to arrow keys. Default:
+    /// `true` only when mouse capture is off; otherwise `false`.
     #[serde(default)]
     pub composer_arrows_scroll: Option<bool>,
 }
@@ -516,6 +578,19 @@ fn default_threshold_secs() -> u64 {
     30
 }
 
+/// Completion sound options.
+#[derive(Debug, Clone, Copy, Deserialize, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum CompletionSound {
+    /// No sound on turn completion.
+    Off,
+    /// System notification beep (default). On Windows uses `MessageBeep`.
+    #[default]
+    Beep,
+    /// Terminal BEL character (`\x07`).
+    Bell,
+}
+
 /// Desktop-notification configuration (OSC 9 / BEL on turn completion).
 #[derive(Debug, Clone, Deserialize, Default)]
 pub struct NotificationsConfig {
@@ -535,6 +610,11 @@ pub struct NotificationsConfig {
     /// Default: `false`.
     #[serde(default)]
     pub include_summary: bool,
+
+    /// Completion sound: `"off"` | `"beep"` | `"bell"`. Default: `"beep"`.
+    /// Plays a sound when every turn finishes (alongside the ✅ marker).
+    #[serde(default)]
+    pub completion_sound: CompletionSound,
 }
 
 fn default_snapshots_enabled() -> bool {
@@ -604,18 +684,45 @@ impl SnapshotsConfig {
 #[serde(rename_all = "snake_case")]
 pub enum SearchProvider {
     /// Bing HTML scraping. No API key needed.
-    #[default]
     Bing,
     /// DuckDuckGo HTML scraping with Bing fallback. No API key needed.
+    #[default]
     #[serde(alias = "duckduckgo")]
     DuckDuckGo,
     /// Tavily AI Search API (<https://tavily.com>). Requires api_key.
     Tavily,
     /// Bocha AI Search API (<https://bochaai.com>). Requires api_key.
     Bocha,
+    /// Metaso AI Search API (<https://metaso.cn>). Uses built-in default key
+    /// or `METASO_API_KEY` env var; configurable via `[search] api_key`.
+    #[serde(alias = "metaso")]
+    Metaso,
+    /// Baidu AI Search API (<https://qianfan.baidubce.com>). Requires api_key.
+    #[serde(
+        alias = "baidu-search",
+        alias = "baidu_ai_search",
+        alias = "baidu_search",
+        alias = "baidu-ai-search"
+    )]
+    Baidu,
 }
 
 impl SearchProvider {
+    #[must_use]
+    pub fn parse(value: &str) -> Option<Self> {
+        match value.trim().to_ascii_lowercase().as_str() {
+            "bing" => Some(Self::Bing),
+            "duckduckgo" | "duck-duck-go" | "duck_duck_go" | "ddg" => Some(Self::DuckDuckGo),
+            "tavily" => Some(Self::Tavily),
+            "bocha" => Some(Self::Bocha),
+            "metaso" => Some(Self::Metaso),
+            "baidu" | "baidu-search" | "baidu_search" | "baidu-ai-search" | "baidu_ai_search" => {
+                Some(Self::Baidu)
+            }
+            _ => None,
+        }
+    }
+
     #[must_use]
     pub fn as_str(self) -> &'static str {
         match self {
@@ -623,21 +730,58 @@ impl SearchProvider {
             Self::DuckDuckGo => "duckduckgo",
             Self::Tavily => "tavily",
             Self::Bocha => "bocha",
+            Self::Metaso => "metaso",
+            Self::Baidu => "baidu",
         }
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SearchProviderSource {
+    Default,
+    Config,
+    EnvOverride,
+}
+
+impl SearchProviderSource {
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Default => "default",
+            Self::Config => "config",
+            Self::EnvOverride => "env override",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct SearchProviderResolution {
+    pub provider: SearchProvider,
+    pub source: SearchProviderSource,
+}
+
 /// Web search provider configuration (`[search]` table in config.toml).
 #[derive(Debug, Clone, Deserialize, Default)]
 pub struct SearchConfig {
-    /// Search provider: `bing` | `duckduckgo` | `tavily` | `bocha`. Default: `bing`.
+    /// Search provider: `bing` | `duckduckgo` | `tavily` | `bocha` | `metaso` | `baidu`. Default: `duckduckgo`.
     #[serde(default)]
     pub provider: Option<SearchProvider>,
-    /// API key for Tavily or Bocha. Not required for Bing or DuckDuckGo.
+    /// API key for Tavily, Bocha, Metaso, or Baidu. Not required for Bing or DuckDuckGo.
+    /// Metaso also falls back to `METASO_API_KEY` env var, then a built-in default.
+    /// Baidu also falls back to `BAIDU_SEARCH_API_KEY` env var.
     #[serde(default)]
     pub api_key: Option<String>,
 }
 
+/// Model-visible tool catalog controls (`[tools]` table in config.toml).
+#[derive(Debug, Clone, Deserialize, Default)]
+pub struct ToolsConfig {
+    /// Native tool names to keep loaded even when they are outside the small
+    /// default core catalog. Unknown names are harmless and simply never match.
+    #[serde(default)]
+    pub always_load: Vec<String>,
+}
+
 /// One configurable footer item.
 ///
 /// Order in the user's `Vec<StatusItem>` is preserved: items in the left
@@ -683,6 +827,8 @@ pub enum StatusItem {
     LastToolElapsed,
     /// Remaining rate-limit budget (placeholder until wired).
     RateLimit,
+    /// Session token usage: input / cache-hit / output.
+    Tokens,
 }
 
 impl StatusItem {
@@ -701,6 +847,8 @@ impl StatusItem {
             StatusItem::Agents,
             StatusItem::ReasoningReplay,
             StatusItem::Cache,
+            StatusItem::GitBranch,
+            StatusItem::Tokens,
         ]
     }
 
@@ -721,6 +869,7 @@ impl StatusItem {
             StatusItem::GitBranch => "git_branch",
             StatusItem::LastToolElapsed => "last_tool_elapsed",
             StatusItem::RateLimit => "rate_limit",
+            StatusItem::Tokens => "tokens",
         }
     }
 
@@ -741,6 +890,7 @@ impl StatusItem {
             StatusItem::GitBranch => "Git branch",
             StatusItem::LastToolElapsed => "Last tool elapsed",
             StatusItem::RateLimit => "Rate-limit remaining",
+            StatusItem::Tokens => "Session tokens",
         }
     }
 
@@ -762,6 +912,7 @@ impl StatusItem {
             StatusItem::GitBranch => "current workspace branch",
             StatusItem::LastToolElapsed => "ms of the most recent tool call (placeholder)",
             StatusItem::RateLimit => "remaining requests in the budget (placeholder)",
+            StatusItem::Tokens => "input / cache-hit / output token totals",
         }
     }
 
@@ -782,6 +933,7 @@ impl StatusItem {
             StatusItem::GitBranch,
             StatusItem::LastToolElapsed,
             StatusItem::RateLimit,
+            StatusItem::Tokens,
         ]
     }
 
@@ -922,10 +1074,15 @@ pub struct Config {
     /// Optional extra HTTP headers sent to model API requests.
     pub http_headers: Option<HashMap<String, String>>,
     pub default_text_model: Option<String>,
+    pub auth_mode: Option<String>,
     /// DeepSeek reasoning-effort tier: `"off" | "low" | "medium" | "high" | "max"`.
     /// Defaults to `"max"` at runtime if unset.
     pub reasoning_effort: Option<String>,
     pub tools_file: Option<String>,
+    /// Native tool catalog controls. `tools_file` is the legacy external
+    /// schema path; this table controls built-in tool loading policy.
+    #[serde(default)]
+    pub tools: Option<ToolsConfig>,
     pub skills_dir: Option<String>,
     pub mcp_config_path: Option<String>,
     pub notes_path: Option<String>,
@@ -955,6 +1112,11 @@ pub struct Config {
     pub sandbox_url: Option<String>,
     /// Optional API key for the external sandbox backend (sent as Bearer token).
     pub sandbox_api_key: Option<String>,
+    /// When true and `/usr/bin/bwrap` is present on Linux, route exec_shell
+    /// through bubblewrap instead of relying solely on Landlock (#2184).
+    /// Defaults to false. Requires the `bubblewrap` package to be installed
+    /// separately — we do NOT vendor bwrap.
+    pub prefer_bwrap: Option<bool>,
     pub managed_config_path: Option<String>,
     pub requirements_path: Option<String>,
     pub max_subagents: Option<usize>,
@@ -994,9 +1156,9 @@ pub struct Config {
     #[serde(default)]
     pub snapshots: Option<SnapshotsConfig>,
 
-    /// Web search provider configuration. When absent, defaults to Bing.
-    /// Set `provider` to `duckduckgo`, `tavily`, or `bocha` to use those
-    /// services instead; Tavily and Bocha also require an `api_key`.
+    /// Web search provider configuration. When absent, defaults to DuckDuckGo.
+    /// Set `provider` to `bing`, `tavily`, or `bocha` to use those services
+    /// instead; Tavily and Bocha also require an `api_key`.
     #[serde(default)]
     pub search: Option<SearchConfig>,
 
@@ -1209,6 +1371,7 @@ pub struct ProviderConfig {
     pub api_key: Option<String>,
     pub base_url: Option<String>,
     pub model: Option<String>,
+    pub auth_mode: Option<String>,
     pub http_headers: Option<HashMap<String, String>>,
 }
 
@@ -1227,12 +1390,18 @@ pub struct ProvidersConfig {
     #[serde(default)]
     pub wanjie_ark: ProviderConfig,
     #[serde(default)]
+    pub volcengine: ProviderConfig,
+    #[serde(default)]
     pub openrouter: ProviderConfig,
     #[serde(default)]
+    pub xiaomi_mimo: ProviderConfig,
+    #[serde(default)]
     pub novita: ProviderConfig,
     #[serde(default)]
     pub fireworks: ProviderConfig,
     #[serde(default)]
+    pub moonshot: ProviderConfig,
+    #[serde(default)]
     pub sglang: ProviderConfig,
     #[serde(default)]
     pub vllm: ProviderConfig,
@@ -1258,6 +1427,35 @@ struct RequirementsFile {
 // === Config Loading ===
 
 impl Config {
+    #[must_use]
+    pub fn search_provider_resolution(&self) -> SearchProviderResolution {
+        if let Ok(raw) = std::env::var("DEEPSEEK_SEARCH_PROVIDER")
+            && let Some(provider) = SearchProvider::parse(&raw)
+        {
+            return SearchProviderResolution {
+                provider,
+                source: SearchProviderSource::EnvOverride,
+            };
+        }
+
+        if let Some(provider) = self.search.as_ref().and_then(|search| search.provider) {
+            return SearchProviderResolution {
+                provider,
+                source: SearchProviderSource::Config,
+            };
+        }
+
+        SearchProviderResolution {
+            provider: SearchProvider::default(),
+            source: SearchProviderSource::Default,
+        }
+    }
+
+    #[must_use]
+    pub fn search_provider(&self) -> SearchProvider {
+        self.search_provider_resolution().provider
+    }
+
     /// Return `true` if the `[auto] cost_saving = true` opt-in is set
     /// (#1207). When true, the auto-mode router biases toward
     /// `deepseek-v4-flash` for ambiguous requests instead of escalating to
@@ -1270,6 +1468,22 @@ impl Config {
             .unwrap_or(false)
     }
 
+    #[must_use]
+    pub fn tools_always_load(&self) -> std::collections::HashSet<String> {
+        self.tools
+            .as_ref()
+            .map(|tools| {
+                tools
+                    .always_load
+                    .iter()
+                    .map(|name| name.trim())
+                    .filter(|name| !name.is_empty())
+                    .map(ToOwned::to_owned)
+                    .collect()
+            })
+            .unwrap_or_default()
+    }
+
     /// Load configuration from disk and merge with environment overrides.
     ///
     /// # Examples
@@ -1341,11 +1555,14 @@ impl Config {
             ApiProvider::Atlascloud => "providers.atlascloud",
             ApiProvider::WanjieArk => "providers.wanjie_ark",
             ApiProvider::Openrouter => "providers.openrouter",
+            ApiProvider::XiaomiMimo => "providers.xiaomi_mimo",
             ApiProvider::Novita => "providers.novita",
             ApiProvider::Fireworks => "providers.fireworks",
+            ApiProvider::Moonshot => "providers.moonshot",
             ApiProvider::Sglang => "providers.sglang",
             ApiProvider::Vllm => "providers.vllm",
             ApiProvider::Ollama => "providers.ollama",
+            ApiProvider::Volcengine => "providers.volcengine",
             ApiProvider::NvidiaNim => "providers.nvidia_nim",
             ApiProvider::Deepseek | ApiProvider::DeepseekCN => return,
         };
@@ -1362,7 +1579,7 @@ impl Config {
             && ApiProvider::parse(provider).is_none()
         {
             anyhow::bail!(
-                "Invalid provider '{provider}': expected deepseek, deepseek-cn, nvidia-nim, openai, atlascloud, wanjie-ark, openrouter, novita, fireworks, sglang, vllm, or ollama."
+                "Invalid provider '{provider}': expected deepseek, deepseek-cn, nvidia-nim, openai, atlascloud, wanjie-ark, openrouter, xiaomi-mimo, novita, fireworks, sglang, vllm, or ollama."
             );
         }
         if let Some(ref key) = self.api_key
@@ -1482,11 +1699,14 @@ impl Config {
             ApiProvider::Atlascloud => &providers.atlascloud,
             ApiProvider::WanjieArk => &providers.wanjie_ark,
             ApiProvider::Openrouter => &providers.openrouter,
+            ApiProvider::XiaomiMimo => &providers.xiaomi_mimo,
             ApiProvider::Novita => &providers.novita,
             ApiProvider::Fireworks => &providers.fireworks,
+            ApiProvider::Moonshot => &providers.moonshot,
             ApiProvider::Sglang => &providers.sglang,
             ApiProvider::Vllm => &providers.vllm,
             ApiProvider::Ollama => &providers.ollama,
+            ApiProvider::Volcengine => &providers.volcengine,
         })
     }
 
@@ -1534,6 +1754,19 @@ impl Config {
                 }
             }
         }
+        let moonshot_config = (provider == ApiProvider::Moonshot)
+            .then(|| self.provider_config())
+            .flatten();
+        let moonshot_uses_kimi_code = moonshot_config.is_some_and(|config| {
+            provider_config_uses_kimi_oauth(config)
+                || config
+                    .base_url
+                    .as_deref()
+                    .is_some_and(moonshot_base_url_uses_kimi_code)
+        });
+        if moonshot_uses_kimi_code {
+            return DEFAULT_KIMI_CODE_MODEL.to_string();
+        }
         if let Some(model) = self.default_text_model.as_deref()
             && (provider_passes_model_through(provider)
                 || self.active_provider_preserves_custom_base_url_model())
@@ -1558,11 +1791,14 @@ impl Config {
             ApiProvider::Atlascloud => DEFAULT_ATLASCLOUD_MODEL,
             ApiProvider::WanjieArk => DEFAULT_WANJIE_ARK_MODEL,
             ApiProvider::Openrouter => DEFAULT_OPENROUTER_MODEL,
+            ApiProvider::XiaomiMimo => DEFAULT_XIAOMI_MIMO_MODEL,
             ApiProvider::Novita => DEFAULT_NOVITA_MODEL,
             ApiProvider::Fireworks => DEFAULT_FIREWORKS_MODEL,
+            ApiProvider::Moonshot => DEFAULT_MOONSHOT_MODEL,
             ApiProvider::Sglang => DEFAULT_SGLANG_MODEL,
             ApiProvider::Vllm => DEFAULT_VLLM_MODEL,
             ApiProvider::Ollama => DEFAULT_OLLAMA_MODEL,
+            ApiProvider::Volcengine => DEFAULT_VOLCENGINE_MODEL,
         }
         .to_string()
     }
@@ -1589,11 +1825,14 @@ impl Config {
             | ApiProvider::Atlascloud
             | ApiProvider::WanjieArk
             | ApiProvider::Openrouter
+            | ApiProvider::XiaomiMimo
             | ApiProvider::Novita
             | ApiProvider::Fireworks
+            | ApiProvider::Moonshot
             | ApiProvider::Sglang
             | ApiProvider::Vllm
-            | ApiProvider::Ollama => None,
+            | ApiProvider::Ollama
+            | ApiProvider::Volcengine => None,
         };
         let base = provider_base.or(root_base).unwrap_or_else(|| {
             match provider {
@@ -1604,11 +1843,23 @@ impl Config {
                 ApiProvider::Atlascloud => DEFAULT_ATLASCLOUD_BASE_URL,
                 ApiProvider::WanjieArk => DEFAULT_WANJIE_ARK_BASE_URL,
                 ApiProvider::Openrouter => DEFAULT_OPENROUTER_BASE_URL,
+                ApiProvider::XiaomiMimo => DEFAULT_XIAOMI_MIMO_BASE_URL,
                 ApiProvider::Novita => DEFAULT_NOVITA_BASE_URL,
                 ApiProvider::Fireworks => DEFAULT_FIREWORKS_BASE_URL,
+                ApiProvider::Moonshot => {
+                    if self
+                        .provider_config()
+                        .is_some_and(provider_config_uses_kimi_oauth)
+                    {
+                        DEFAULT_KIMI_CODE_BASE_URL
+                    } else {
+                        DEFAULT_MOONSHOT_BASE_URL
+                    }
+                }
                 ApiProvider::Sglang => DEFAULT_SGLANG_BASE_URL,
                 ApiProvider::Vllm => DEFAULT_VLLM_BASE_URL,
                 ApiProvider::Ollama => DEFAULT_OLLAMA_BASE_URL,
+                ApiProvider::Volcengine => DEFAULT_VOLCENGINE_BASE_URL,
             }
             .to_string()
         });
@@ -1637,11 +1888,14 @@ impl Config {
             ApiProvider::Atlascloud => "atlascloud",
             ApiProvider::WanjieArk => "wanjie-ark",
             ApiProvider::Openrouter => "openrouter",
+            ApiProvider::XiaomiMimo => "xiaomi-mimo",
             ApiProvider::Novita => "novita",
             ApiProvider::Fireworks => "fireworks",
+            ApiProvider::Moonshot => "moonshot",
             ApiProvider::Sglang => "sglang",
             ApiProvider::Vllm => "vllm",
             ApiProvider::Ollama => "ollama",
+            ApiProvider::Volcengine => "volcengine",
         };
 
         // 0. DeepSeek compatibility slot. The legacy top-level `api_key`
@@ -1655,6 +1909,14 @@ impl Config {
             return Ok(configured.clone());
         }
 
+        if provider == ApiProvider::Moonshot
+            && self
+                .provider_config_for(provider)
+                .is_some_and(provider_config_uses_kimi_oauth)
+        {
+            return kimi_cli_oauth_access_token();
+        }
+
         // 1. Config file (provider-scoped slot). This intentionally wins
         // over ambient env so `codewhale auth set` fixes stale shell exports.
         if let Some(configured) = self
@@ -1713,6 +1975,10 @@ impl Config {
                 "OpenRouter API key not found. Run 'codewhale auth set --provider openrouter', \
                  set OPENROUTER_API_KEY, or add [providers.openrouter] api_key in ~/.deepseek/config.toml."
             ),
+            ApiProvider::XiaomiMimo => anyhow::bail!(
+                "Xiaomi MiMo API key not found. Run 'codewhale auth set --provider xiaomi-mimo', \
+                 set XIAOMI_MIMO_API_KEY/MIMO_API_KEY, or add [providers.xiaomi_mimo] api_key in ~/.deepseek/config.toml."
+            ),
             ApiProvider::Novita => anyhow::bail!(
                 "Novita API key not found. Run 'codewhale auth set --provider novita', \
                  set NOVITA_API_KEY, or add [providers.novita] api_key in ~/.deepseek/config.toml."
@@ -1721,9 +1987,18 @@ impl Config {
                 "Fireworks AI API key not found. Run 'codewhale auth set --provider fireworks', \
                  set FIREWORKS_API_KEY, or add [providers.fireworks] api_key in ~/.deepseek/config.toml."
             ),
+            ApiProvider::Moonshot => anyhow::bail!(
+                "Moonshot/Kimi API key not found. Run 'codewhale auth set --provider moonshot', \
+                 set MOONSHOT_API_KEY/KIMI_API_KEY, or add [providers.moonshot] api_key. \
+                 For a Kimi Code plan key, set [providers.moonshot] base_url = \
+                 \"https://api.kimi.com/coding/v1\" and model = \"kimi-for-coding\"."
+            ),
             // Self-hosted deployments commonly run without auth on localhost.
             // Return an empty key and let the client omit the Authorization header.
-            ApiProvider::Sglang | ApiProvider::Vllm | ApiProvider::Ollama => Ok(String::new()),
+            ApiProvider::Sglang
+            | ApiProvider::Vllm
+            | ApiProvider::Ollama
+            | ApiProvider::Volcengine => Ok(String::new()),
         }
     }
 
@@ -1967,7 +2242,7 @@ fn default_config_path() -> Option<PathBuf> {
     env_config_path().or_else(home_config_path)
 }
 
-fn effective_home_dir() -> Option<PathBuf> {
+pub(crate) fn effective_home_dir() -> Option<PathBuf> {
     if let Some(path) = std::env::var_os("HOME") {
         let path = PathBuf::from(path);
         if !path.as_os_str().is_empty() {
@@ -1999,7 +2274,13 @@ fn effective_home_dir() -> Option<PathBuf> {
 }
 
 fn home_config_path() -> Option<PathBuf> {
-    effective_home_dir().map(|home| home.join(".deepseek").join("config.toml"))
+    effective_home_dir().map(|home| {
+        let primary = home.join(".codewhale").join("config.toml");
+        if primary.exists() {
+            return primary;
+        }
+        home.join(".deepseek").join("config.toml")
+    })
 }
 
 #[must_use]
@@ -2162,7 +2443,13 @@ fn default_managed_config_path() -> Option<PathBuf> {
     }
     #[cfg(not(unix))]
     {
-        effective_home_dir().map(|home| home.join(".deepseek").join("managed_config.toml"))
+        effective_home_dir().map(|home| {
+            let primary = home.join(".codewhale").join("managed_config.toml");
+            if primary.exists() {
+                return primary;
+            }
+            home.join(".deepseek").join("managed_config.toml")
+        })
     }
 }
 
@@ -2173,7 +2460,13 @@ fn default_requirements_path() -> Option<PathBuf> {
     }
     #[cfg(not(unix))]
     {
-        effective_home_dir().map(|home| home.join(".deepseek").join("requirements.toml"))
+        effective_home_dir().map(|home| {
+            let primary = home.join(".codewhale").join("requirements.toml");
+            if primary.exists() {
+                return primary;
+            }
+            home.join(".deepseek").join("requirements.toml")
+        })
     }
 }
 
@@ -2198,24 +2491,60 @@ fn default_skills_dir() -> Option<PathBuf> {
 }
 
 fn default_mcp_config_path() -> Option<PathBuf> {
-    effective_home_dir().map(|home| home.join(".deepseek").join("mcp.json"))
+    effective_home_dir().map(|home| {
+        let primary = home.join(".codewhale").join("mcp.json");
+        if primary.exists() {
+            return primary;
+        }
+        home.join(".deepseek").join("mcp.json")
+    })
 }
 
 fn default_notes_path() -> Option<PathBuf> {
-    effective_home_dir().map(|home| home.join(".deepseek").join("notes.txt"))
+    effective_home_dir().map(|home| {
+        let primary = home.join(".codewhale").join("notes.txt");
+        if primary.exists() {
+            return primary;
+        }
+        home.join(".deepseek").join("notes.txt")
+    })
 }
 
 fn default_memory_path() -> Option<PathBuf> {
-    effective_home_dir().map(|home| home.join(".deepseek").join("memory.md"))
+    effective_home_dir().map(|home| {
+        let primary = home.join(".codewhale").join("memory.md");
+        if primary.exists() {
+            return primary;
+        }
+        home.join(".deepseek").join("memory.md")
+    })
 }
 
 // === Environment Overrides ===
 
+/// Read a CodeWhale env var, preferring the `CODEWHALE_*` form over the
+/// legacy `DEEPSEEK_*` form. Empty values are ignored so a blank shell export
+/// does not erase configured provider settings.
+fn codewhale_env_var(
+    codewhale_name: &str,
+    legacy_name: &str,
+) -> Result<String, std::env::VarError> {
+    std::env::var(codewhale_name)
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+        .or_else(|| {
+            std::env::var(legacy_name)
+                .ok()
+                .filter(|value| !value.trim().is_empty())
+        })
+        .ok_or(std::env::VarError::NotPresent)
+}
+
 fn apply_env_overrides(config: &mut Config) {
-    if let Ok(value) = std::env::var("DEEPSEEK_PROVIDER") {
+    if let Ok(value) = codewhale_env_var("CODEWHALE_PROVIDER", "DEEPSEEK_PROVIDER") {
         config.provider = Some(value);
     }
-    if let Ok(value) = std::env::var("DEEPSEEK_BASE_URL") {
+    if let Ok(value) = codewhale_env_var("CODEWHALE_BASE_URL", "DEEPSEEK_BASE_URL") {
         match config.api_provider() {
             ApiProvider::Deepseek | ApiProvider::DeepseekCN => {
                 config.base_url = Some(value);
@@ -2241,6 +2570,13 @@ fn apply_env_overrides(config: &mut Config) {
                     .openrouter
                     .base_url = Some(value);
             }
+            ApiProvider::XiaomiMimo => {
+                config
+                    .providers
+                    .get_or_insert_with(ProvidersConfig::default)
+                    .xiaomi_mimo
+                    .base_url = Some(value);
+            }
             ApiProvider::WanjieArk => {
                 config
                     .providers
@@ -2262,6 +2598,13 @@ fn apply_env_overrides(config: &mut Config) {
                     .fireworks
                     .base_url = Some(value);
             }
+            ApiProvider::Moonshot => {
+                config
+                    .providers
+                    .get_or_insert_with(ProvidersConfig::default)
+                    .moonshot
+                    .base_url = Some(value);
+            }
             ApiProvider::Sglang => {
                 config
                     .providers
@@ -2283,6 +2626,13 @@ fn apply_env_overrides(config: &mut Config) {
                     .ollama
                     .base_url = Some(value);
             }
+            ApiProvider::Volcengine => {
+                config
+                    .providers
+                    .get_or_insert_with(ProvidersConfig::default)
+                    .volcengine
+                    .base_url = Some(value);
+            }
             ApiProvider::Atlascloud => {
                 config
                     .providers
@@ -2336,6 +2686,17 @@ fn apply_env_overrides(config: &mut Config) {
             .openrouter
             .base_url = Some(value);
     }
+    if matches!(config.api_provider(), ApiProvider::XiaomiMimo)
+        && let Ok(value) =
+            std::env::var("XIAOMI_MIMO_BASE_URL").or_else(|_| std::env::var("MIMO_BASE_URL"))
+        && !value.trim().is_empty()
+    {
+        config
+            .providers
+            .get_or_insert_with(ProvidersConfig::default)
+            .xiaomi_mimo
+            .base_url = Some(value);
+    }
     if matches!(config.api_provider(), ApiProvider::WanjieArk)
         && let Ok(value) = std::env::var("WANJIE_ARK_BASE_URL")
             .or_else(|_| std::env::var("WANJIE_BASE_URL"))
@@ -2368,6 +2729,17 @@ fn apply_env_overrides(config: &mut Config) {
             .fireworks
             .base_url = Some(value);
     }
+    if matches!(config.api_provider(), ApiProvider::Moonshot)
+        && let Ok(value) =
+            std::env::var("MOONSHOT_BASE_URL").or_else(|_| std::env::var("KIMI_BASE_URL"))
+        && !value.trim().is_empty()
+    {
+        config
+            .providers
+            .get_or_insert_with(ProvidersConfig::default)
+            .moonshot
+            .base_url = Some(value);
+    }
     if matches!(config.api_provider(), ApiProvider::Sglang)
         && let Ok(value) = std::env::var("SGLANG_BASE_URL")
         && !value.trim().is_empty()
@@ -2408,11 +2780,14 @@ fn apply_env_overrides(config: &mut Config) {
             ApiProvider::Atlascloud => &mut providers.atlascloud,
             ApiProvider::WanjieArk => &mut providers.wanjie_ark,
             ApiProvider::Openrouter => &mut providers.openrouter,
+            ApiProvider::XiaomiMimo => &mut providers.xiaomi_mimo,
             ApiProvider::Novita => &mut providers.novita,
             ApiProvider::Fireworks => &mut providers.fireworks,
+            ApiProvider::Moonshot => &mut providers.moonshot,
             ApiProvider::Sglang => &mut providers.sglang,
             ApiProvider::Vllm => &mut providers.vllm,
             ApiProvider::Ollama => &mut providers.ollama,
+            ApiProvider::Volcengine => &mut providers.volcengine,
         };
         let mut provider_headers = entry.http_headers.clone().unwrap_or_default();
         provider_headers.extend(headers);
@@ -2452,6 +2827,16 @@ fn apply_env_overrides(config: &mut Config) {
             .openai
             .model = Some(value);
     }
+    if matches!(config.api_provider(), ApiProvider::XiaomiMimo)
+        && let Ok(value) =
+            std::env::var("XIAOMI_MIMO_MODEL").or_else(|_| std::env::var("MIMO_MODEL"))
+    {
+        config
+            .providers
+            .get_or_insert_with(ProvidersConfig::default)
+            .xiaomi_mimo
+            .model = Some(value);
+    }
     if matches!(config.api_provider(), ApiProvider::Atlascloud)
         && let Ok(value) = std::env::var("ATLASCLOUD_MODEL")
     {
@@ -2468,8 +2853,24 @@ fn apply_env_overrides(config: &mut Config) {
             .wanjie_ark
             .model = Some(value);
     }
-    if let Ok(value) =
-        std::env::var("DEEPSEEK_MODEL").or_else(|_| std::env::var("DEEPSEEK_DEFAULT_TEXT_MODEL"))
+    if matches!(config.api_provider(), ApiProvider::Moonshot)
+        && let Ok(value) = std::env::var("MOONSHOT_MODEL")
+            .or_else(|_| std::env::var("KIMI_MODEL_NAME"))
+            .or_else(|_| std::env::var("KIMI_MODEL"))
+    {
+        config
+            .providers
+            .get_or_insert_with(ProvidersConfig::default)
+            .moonshot
+            .model = Some(value);
+    }
+    if let Some(value) = codewhale_env_var("CODEWHALE_MODEL", "DEEPSEEK_MODEL")
+        .ok()
+        .or_else(|| {
+            std::env::var("DEEPSEEK_DEFAULT_TEXT_MODEL")
+                .ok()
+                .filter(|value| !value.trim().is_empty())
+        })
     {
         // The CLI `--model` handoff always sets DEEPSEEK_MODEL, never the
         // provider-specific *_MODEL var. The legacy root `default_text_model`
@@ -2495,11 +2896,14 @@ fn apply_env_overrides(config: &mut Config) {
                 ApiProvider::Atlascloud => &mut providers.atlascloud,
                 ApiProvider::WanjieArk => &mut providers.wanjie_ark,
                 ApiProvider::Openrouter => &mut providers.openrouter,
+                ApiProvider::XiaomiMimo => &mut providers.xiaomi_mimo,
                 ApiProvider::Novita => &mut providers.novita,
                 ApiProvider::Fireworks => &mut providers.fireworks,
+                ApiProvider::Moonshot => &mut providers.moonshot,
                 ApiProvider::Sglang => &mut providers.sglang,
                 ApiProvider::Vllm => &mut providers.vllm,
                 ApiProvider::Ollama => &mut providers.ollama,
+                ApiProvider::Volcengine => &mut providers.volcengine,
             };
             entry.model = Some(value);
         }
@@ -2555,6 +2959,14 @@ fn apply_env_overrides(config: &mut Config) {
     if let Ok(value) = std::env::var("DEEPSEEK_MANAGED_CONFIG_PATH") {
         config.managed_config_path = Some(value);
     }
+    if let Ok(value) = std::env::var("DEEPSEEK_SEARCH_API_KEY")
+        && !value.trim().is_empty()
+    {
+        config
+            .search
+            .get_or_insert_with(SearchConfig::default)
+            .api_key = Some(value);
+    }
     if let Ok(value) = std::env::var("DEEPSEEK_REQUIREMENTS_PATH") {
         config.requirements_path = Some(value);
     }
@@ -2724,6 +3136,12 @@ fn normalize_model_config(config: &mut Config) {
         {
             providers.fireworks.model = Some(normalized);
         }
+        if let Some(model) = providers.moonshot.model.as_deref()
+            && !provider_entry_uses_custom_base_url(ApiProvider::Moonshot, &providers.moonshot)
+            && let Some(normalized) = normalize_model_for_provider(ApiProvider::Moonshot, model)
+        {
+            providers.moonshot.model = Some(normalized);
+        }
         if let Some(model) = providers.sglang.model.as_deref()
             && !provider_entry_uses_custom_base_url(ApiProvider::Sglang, &providers.sglang)
             && let Some(normalized) = normalize_model_for_provider(ApiProvider::Sglang, model)
@@ -2752,6 +3170,9 @@ pub(crate) fn provider_passes_model_through(provider: ApiProvider) -> bool {
         ApiProvider::Openai
             | ApiProvider::Atlascloud
             | ApiProvider::WanjieArk
+            | ApiProvider::Volcengine
+            | ApiProvider::XiaomiMimo
+            | ApiProvider::Moonshot
             | ApiProvider::Ollama
     )
 }
@@ -2772,11 +3193,14 @@ fn default_base_url_for_provider(provider: ApiProvider) -> &'static str {
         ApiProvider::Atlascloud => DEFAULT_ATLASCLOUD_BASE_URL,
         ApiProvider::WanjieArk => DEFAULT_WANJIE_ARK_BASE_URL,
         ApiProvider::Openrouter => DEFAULT_OPENROUTER_BASE_URL,
+        ApiProvider::XiaomiMimo => DEFAULT_XIAOMI_MIMO_BASE_URL,
         ApiProvider::Novita => DEFAULT_NOVITA_BASE_URL,
         ApiProvider::Fireworks => DEFAULT_FIREWORKS_BASE_URL,
+        ApiProvider::Moonshot => DEFAULT_MOONSHOT_BASE_URL,
         ApiProvider::Sglang => DEFAULT_SGLANG_BASE_URL,
         ApiProvider::Vllm => DEFAULT_VLLM_BASE_URL,
         ApiProvider::Ollama => DEFAULT_OLLAMA_BASE_URL,
+        ApiProvider::Volcengine => DEFAULT_VOLCENGINE_BASE_URL,
     }
 }
 
@@ -2788,6 +3212,31 @@ fn provider_preserves_custom_base_url_model(provider: ApiProvider, base_url: &st
     base_url_is_custom_for_provider(provider, base_url)
 }
 
+fn moonshot_base_url_uses_kimi_code(base_url: &str) -> bool {
+    let normalized = normalize_base_url(base_url).to_ascii_lowercase();
+    normalized == DEFAULT_KIMI_CODE_BASE_URL
+        || normalized == "https://api.kimi.com/coding"
+        || normalized.starts_with("https://api.kimi.com/coding/")
+}
+
+fn provider_config_uses_kimi_oauth(config: &ProviderConfig) -> bool {
+    config
+        .auth_mode
+        .as_deref()
+        .is_some_and(auth_mode_uses_kimi_oauth)
+}
+
+fn auth_mode_uses_kimi_oauth(mode: &str) -> bool {
+    matches!(
+        normalize_auth_mode(mode).as_str(),
+        "kimi" | "kimi_oauth" | "kimi_cli" | "oauth"
+    )
+}
+
+fn normalize_auth_mode(mode: &str) -> String {
+    mode.trim().to_ascii_lowercase().replace(['-', ' '], "_")
+}
+
 fn base_url_uses_local_host(base_url: &str) -> bool {
     let Some(host) = base_url_host(base_url) else {
         return false;
@@ -2902,8 +3351,10 @@ fn merge_config(base: Config, override_cfg: Config) -> Config {
         base_url: override_cfg.base_url.or(base.base_url),
         http_headers: override_cfg.http_headers.or(base.http_headers),
         default_text_model: override_cfg.default_text_model.or(base.default_text_model),
+        auth_mode: override_cfg.auth_mode.or(base.auth_mode),
         reasoning_effort: override_cfg.reasoning_effort.or(base.reasoning_effort),
         tools_file: override_cfg.tools_file.or(base.tools_file),
+        tools: override_cfg.tools.or(base.tools),
         skills_dir: override_cfg.skills_dir.or(base.skills_dir),
         mcp_config_path: override_cfg.mcp_config_path.or(base.mcp_config_path),
         notes_path: override_cfg.notes_path.or(base.notes_path),
@@ -2920,6 +3371,7 @@ fn merge_config(base: Config, override_cfg: Config) -> Config {
         sandbox_backend: override_cfg.sandbox_backend.or(base.sandbox_backend),
         sandbox_url: override_cfg.sandbox_url.or(base.sandbox_url),
         sandbox_api_key: override_cfg.sandbox_api_key.or(base.sandbox_api_key),
+        prefer_bwrap: override_cfg.prefer_bwrap.or(base.prefer_bwrap),
         managed_config_path: override_cfg
             .managed_config_path
             .or(base.managed_config_path),
@@ -2979,6 +3431,7 @@ fn merge_provider_config(base: ProviderConfig, override_cfg: ProviderConfig) ->
         api_key: override_cfg.api_key.or(base.api_key),
         base_url: override_cfg.base_url.or(base.base_url),
         model: override_cfg.model.or(base.model),
+        auth_mode: override_cfg.auth_mode.or(base.auth_mode),
         http_headers: override_cfg.http_headers.or(base.http_headers),
     }
 }
@@ -2999,11 +3452,14 @@ fn merge_providers(
             atlascloud: merge_provider_config(base.atlascloud, override_cfg.atlascloud),
             wanjie_ark: merge_provider_config(base.wanjie_ark, override_cfg.wanjie_ark),
             openrouter: merge_provider_config(base.openrouter, override_cfg.openrouter),
+            xiaomi_mimo: merge_provider_config(base.xiaomi_mimo, override_cfg.xiaomi_mimo),
             novita: merge_provider_config(base.novita, override_cfg.novita),
             fireworks: merge_provider_config(base.fireworks, override_cfg.fireworks),
+            moonshot: merge_provider_config(base.moonshot, override_cfg.moonshot),
             sglang: merge_provider_config(base.sglang, override_cfg.sglang),
             vllm: merge_provider_config(base.vllm, override_cfg.vllm),
             ollama: merge_provider_config(base.ollama, override_cfg.ollama),
+            volcengine: merge_provider_config(base.volcengine, override_cfg.volcengine),
         }),
     }
 }
@@ -3373,6 +3829,14 @@ pub fn has_api_key(config: &Config) -> bool {
 pub fn active_provider_has_config_api_key(config: &Config) -> bool {
     let provider = config.api_provider();
 
+    if provider == ApiProvider::Moonshot
+        && config
+            .provider_config_for(provider)
+            .is_some_and(provider_config_uses_kimi_oauth)
+    {
+        return kimi_cli_credentials_present();
+    }
+
     if config
         .provider_config_for(provider)
         .and_then(|entry| entry.api_key.as_ref())
@@ -3410,13 +3874,26 @@ pub fn active_provider_has_env_api_key(config: &Config) -> bool {
         ApiProvider::Openrouter => {
             std::env::var("OPENROUTER_API_KEY").is_ok_and(|k| !k.trim().is_empty())
         }
+        ApiProvider::XiaomiMimo => {
+            std::env::var("XIAOMI_MIMO_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+                || std::env::var("MIMO_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+        }
         ApiProvider::Novita => std::env::var("NOVITA_API_KEY").is_ok_and(|k| !k.trim().is_empty()),
         ApiProvider::Fireworks => {
             std::env::var("FIREWORKS_API_KEY").is_ok_and(|k| !k.trim().is_empty())
         }
+        ApiProvider::Moonshot => {
+            std::env::var("MOONSHOT_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+                || std::env::var("KIMI_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+        }
         ApiProvider::Sglang => std::env::var("SGLANG_API_KEY").is_ok_and(|k| !k.trim().is_empty()),
         ApiProvider::Vllm => std::env::var("VLLM_API_KEY").is_ok_and(|k| !k.trim().is_empty()),
         ApiProvider::Ollama => std::env::var("OLLAMA_API_KEY").is_ok_and(|k| !k.trim().is_empty()),
+        ApiProvider::Volcengine => {
+            std::env::var("VOLCENGINE_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+                || std::env::var("VOLCENGINE_ARK_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+                || std::env::var("ARK_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+        }
     }
 }
 
@@ -3437,11 +3914,14 @@ pub fn has_api_key_for(config: &Config, provider: ApiProvider) -> bool {
         ApiProvider::Atlascloud => "ATLASCLOUD_API_KEY",
         ApiProvider::WanjieArk => "WANJIE_ARK_API_KEY",
         ApiProvider::Openrouter => "OPENROUTER_API_KEY",
+        ApiProvider::XiaomiMimo => "XIAOMI_MIMO_API_KEY",
         ApiProvider::Novita => "NOVITA_API_KEY",
         ApiProvider::Fireworks => "FIREWORKS_API_KEY",
+        ApiProvider::Moonshot => "MOONSHOT_API_KEY",
         ApiProvider::Sglang => "SGLANG_API_KEY",
         ApiProvider::Vllm => "VLLM_API_KEY",
         ApiProvider::Ollama => "OLLAMA_API_KEY",
+        ApiProvider::Volcengine => "VOLCENGINE_API_KEY",
     };
     if std::env::var(env_var).is_ok_and(|k| !k.trim().is_empty()) {
         return true;
@@ -3457,6 +3937,24 @@ pub fn has_api_key_for(config: &Config, provider: ApiProvider) -> bool {
     {
         return true;
     }
+    if matches!(provider, ApiProvider::XiaomiMimo)
+        && std::env::var("MIMO_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+    {
+        return true;
+    }
+    if matches!(provider, ApiProvider::Moonshot)
+        && std::env::var("KIMI_API_KEY").is_ok_and(|k| !k.trim().is_empty())
+    {
+        return true;
+    }
+
+    if provider == ApiProvider::Moonshot
+        && config
+            .provider_config_for(provider)
+            .is_some_and(provider_config_uses_kimi_oauth)
+    {
+        return kimi_cli_credentials_present();
+    }
 
     // Self-hosted providers typically run without authentication.
     if matches!(
@@ -3517,11 +4015,14 @@ pub fn save_api_key_for(provider: ApiProvider, api_key: &str) -> Result<PathBuf>
         ApiProvider::Atlascloud => "providers.atlascloud",
         ApiProvider::WanjieArk => "providers.wanjie_ark",
         ApiProvider::Openrouter => "providers.openrouter",
+        ApiProvider::XiaomiMimo => "providers.xiaomi_mimo",
         ApiProvider::Novita => "providers.novita",
         ApiProvider::Fireworks => "providers.fireworks",
+        ApiProvider::Moonshot => "providers.moonshot",
         ApiProvider::Sglang => "providers.sglang",
         ApiProvider::Vllm => "providers.vllm",
         ApiProvider::Ollama => "providers.ollama",
+        ApiProvider::Volcengine => "providers.volcengine",
     };
 
     // Parse existing TOML (or start fresh) so we can edit the right table
@@ -3553,11 +4054,14 @@ pub fn save_api_key_for(provider: ApiProvider, api_key: &str) -> Result<PathBuf>
         ApiProvider::Atlascloud => "atlascloud",
         ApiProvider::WanjieArk => "wanjie_ark",
         ApiProvider::Openrouter => "openrouter",
+        ApiProvider::XiaomiMimo => "xiaomi_mimo",
         ApiProvider::Novita => "novita",
         ApiProvider::Fireworks => "fireworks",
+        ApiProvider::Moonshot => "moonshot",
         ApiProvider::Sglang => "sglang",
         ApiProvider::Vllm => "vllm",
         ApiProvider::Ollama => "ollama",
+        ApiProvider::Volcengine => "volcengine",
     };
     let entry = providers
         .entry(key_inside.to_string())
@@ -3584,6 +4088,217 @@ pub fn save_api_key_for(provider: ApiProvider, api_key: &str) -> Result<PathBuf>
     Ok(config_path)
 }
 
+pub fn save_provider_auth_mode_for(provider: ApiProvider, auth_mode: &str) -> Result<PathBuf> {
+    let config_path = default_config_path()
+        .context("Failed to resolve config path: home directory not found.")?;
+    ensure_parent_dir(&config_path)?;
+
+    let mut doc: toml::Value = if config_path.exists() {
+        let raw = fs::read_to_string(&config_path)?;
+        toml::from_str(&raw)
+            .with_context(|| format!("Failed to parse config at {}", config_path.display()))?
+    } else {
+        toml::Value::Table(toml::value::Table::new())
+    };
+
+    let table = doc
+        .as_table_mut()
+        .context("Config root must be a TOML table.")?;
+    let providers = table
+        .entry("providers".to_string())
+        .or_insert_with(|| toml::Value::Table(toml::value::Table::new()))
+        .as_table_mut()
+        .context("`providers` must be a table.")?;
+    let key_inside = provider_config_key(provider).context("provider auth mode key")?;
+    let entry = providers
+        .entry(key_inside.to_string())
+        .or_insert_with(|| toml::Value::Table(toml::value::Table::new()))
+        .as_table_mut()
+        .with_context(|| format!("`providers.{key_inside}` must be a table."))?;
+    entry.insert(
+        "auth_mode".to_string(),
+        toml::Value::String(auth_mode.to_string()),
+    );
+
+    let serialized = toml::to_string_pretty(&doc).context("failed to serialize updated config")?;
+    write_config_file_secure(&config_path, &serialized)
+        .with_context(|| format!("Failed to write config to {}", config_path.display()))?;
+    log_sensitive_event(
+        "credential.auth_mode.set",
+        json!({
+            "backend": "config_file",
+            "provider": provider.as_str(),
+            "auth_mode": auth_mode,
+            "config_path": config_path.display().to_string(),
+        }),
+    );
+    Ok(config_path)
+}
+
+fn provider_config_key(provider: ApiProvider) -> Result<&'static str> {
+    match provider {
+        ApiProvider::Deepseek | ApiProvider::DeepseekCN => {
+            anyhow::bail!("DeepSeek stores auth at the root config level")
+        }
+        ApiProvider::NvidiaNim => Ok("nvidia_nim"),
+        ApiProvider::Openai => Ok("openai"),
+        ApiProvider::Atlascloud => Ok("atlascloud"),
+        ApiProvider::WanjieArk => Ok("wanjie_ark"),
+        ApiProvider::Volcengine => Ok("volcengine"),
+        ApiProvider::Openrouter => Ok("openrouter"),
+        ApiProvider::XiaomiMimo => Ok("xiaomi_mimo"),
+        ApiProvider::Novita => Ok("novita"),
+        ApiProvider::Fireworks => Ok("fireworks"),
+        ApiProvider::Moonshot => Ok("moonshot"),
+        ApiProvider::Sglang => Ok("sglang"),
+        ApiProvider::Vllm => Ok("vllm"),
+        ApiProvider::Ollama => Ok("ollama"),
+    }
+}
+
+const KIMI_CODE_CLIENT_ID: &str = "17e5f671-d194-4dfb-9706-5516cb48c098";
+const KIMI_CODE_CREDENTIAL_FILE: &str = "kimi-code.json";
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+struct KimiOAuthCredential {
+    access_token: Option<String>,
+    refresh_token: Option<String>,
+    expires_at: Option<f64>,
+    expires_in: Option<f64>,
+    scope: Option<String>,
+    token_type: Option<String>,
+}
+
+fn kimi_cli_oauth_access_token() -> Result<String> {
+    let path = kimi_cli_oauth_credentials_path()?;
+    let raw = fs::read_to_string(&path).with_context(|| {
+        format!(
+            "Kimi OAuth credentials not found at {}. Run `kimi login`, then set \
+             [providers.moonshot] auth_mode = \"kimi_oauth\".",
+            path.display()
+        )
+    })?;
+    let mut credential: KimiOAuthCredential =
+        serde_json::from_str(&raw).context("Failed to parse Kimi OAuth credentials")?;
+
+    if kimi_oauth_access_token_is_fresh(&credential) {
+        return credential
+            .access_token
+            .filter(|token| !token.trim().is_empty())
+            .context("Kimi OAuth access token is empty");
+    }
+
+    let refresh_token = credential
+        .refresh_token
+        .as_deref()
+        .filter(|token| !token.trim().is_empty())
+        .context("Kimi OAuth refresh token is empty. Run `kimi login` again.")?;
+    credential = refresh_kimi_oauth_token(refresh_token)?;
+    write_kimi_oauth_credential(&path, &credential)?;
+    credential
+        .access_token
+        .filter(|token| !token.trim().is_empty())
+        .context("Kimi OAuth refresh returned an empty access token")
+}
+
+fn kimi_oauth_access_token_is_fresh(credential: &KimiOAuthCredential) -> bool {
+    let Some(now) = now_unix_secs() else {
+        return false;
+    };
+
+    credential
+        .access_token
+        .as_deref()
+        .is_some_and(|token| !token.trim().is_empty())
+        && credential
+            .expires_at
+            .is_some_and(|expires_at| expires_at - now > 60.0)
+}
+
+fn refresh_kimi_oauth_token(refresh_token: &str) -> Result<KimiOAuthCredential> {
+    let oauth_host = std::env::var("KIMI_CODE_OAUTH_HOST")
+        .or_else(|_| std::env::var("KIMI_OAUTH_HOST"))
+        .unwrap_or_else(|_| "https://auth.kimi.com".to_string());
+    let url = format!("{}/api/oauth/token", oauth_host.trim_end_matches('/'));
+    let client = reqwest::blocking::Client::builder()
+        .timeout(Duration::from_secs(15))
+        .build()
+        .context("Failed to build Kimi OAuth refresh client")?;
+    let params = [
+        ("client_id", KIMI_CODE_CLIENT_ID),
+        ("grant_type", "refresh_token"),
+        ("refresh_token", refresh_token),
+    ];
+    let response = client
+        .post(url)
+        .header("X-Msh-Platform", "kimi_cli")
+        .header("X-Msh-Version", env!("CARGO_PKG_VERSION"))
+        .form(&params)
+        .send()
+        .context("Kimi OAuth refresh request failed")?;
+    let status = response.status();
+    if !status.is_success() {
+        anyhow::bail!("Kimi OAuth refresh failed with HTTP {status}. Run `kimi login` again.");
+    }
+
+    let mut refreshed: KimiOAuthCredential = response
+        .json()
+        .context("Failed to parse Kimi OAuth refresh response")?;
+    if let Some(expires_in) = refreshed.expires_in
+        && let Some(now) = now_unix_secs()
+    {
+        refreshed.expires_at = Some(now + expires_in);
+    }
+    Ok(refreshed)
+}
+
+fn kimi_cli_oauth_credentials_path() -> Result<PathBuf> {
+    let share_dir = std::env::var("KIMI_SHARE_DIR")
+        .map(PathBuf::from)
+        .or_else(|_| {
+            effective_home_dir()
+                .map(|home| home.join(".kimi"))
+                .ok_or(std::env::VarError::NotPresent)
+        })
+        .context("Failed to resolve Kimi share directory")?;
+    Ok(share_dir
+        .join("credentials")
+        .join(KIMI_CODE_CREDENTIAL_FILE))
+}
+
+fn write_kimi_oauth_credential(path: &Path, credential: &KimiOAuthCredential) -> Result<()> {
+    let serialized = serde_json::to_vec_pretty(credential)
+        .context("Failed to serialize Kimi OAuth credentials")?;
+    crate::utils::write_atomic(path, &serialized).with_context(|| {
+        format!(
+            "Failed to write Kimi OAuth credentials to {}",
+            path.display()
+        )
+    })?;
+    #[cfg(unix)]
+    if let Err(err) = fs::set_permissions(path, fs::Permissions::from_mode(0o600)) {
+        tracing::warn!(
+            target: "codewhale::config",
+            path = %path.display(),
+            error = %err,
+            "could not enforce 0o600 on Kimi OAuth credentials; relying on host ACLs"
+        );
+    }
+    Ok(())
+}
+
+fn now_unix_secs() -> Option<f64> {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|duration| duration.as_secs_f64())
+        .ok()
+}
+
+#[must_use]
+pub fn kimi_cli_credentials_present() -> bool {
+    kimi_cli_oauth_credentials_path().is_ok_and(|path| path.exists())
+}
+
 /// Clear the API key from config-file storage.
 ///
 /// `/logout` calls this to wipe credentials so the next request can't
@@ -3678,8 +4393,25 @@ mod tests {
     }
 
     #[test]
-    fn search_provider_defaults_to_bing() {
-        assert_eq!(SearchProvider::default(), SearchProvider::Bing);
+    fn search_provider_defaults_to_duckduckgo() {
+        assert_eq!(SearchProvider::default(), SearchProvider::DuckDuckGo);
+    }
+
+    #[test]
+    fn tools_always_load_parses_and_trims_names() {
+        let parsed: ConfigFile = toml::from_str(
+            r#"
+            [tools]
+            always_load = ["git_show", " notify ", ""]
+            "#,
+        )
+        .expect("tools config");
+
+        let names = parsed.base.tools_always_load();
+
+        assert!(names.contains("git_show"));
+        assert!(names.contains("notify"));
+        assert!(!names.contains(""));
     }
 
     #[test]
@@ -3698,6 +4430,144 @@ mod tests {
         );
     }
 
+    #[test]
+    fn explicit_baidu_search_provider_is_preserved() {
+        let config: Config = toml::from_str(
+            r#"
+            [search]
+            provider = "baidu"
+            "#,
+        )
+        .expect("search config");
+
+        assert_eq!(
+            config.search.and_then(|search| search.provider),
+            Some(SearchProvider::Baidu)
+        );
+    }
+
+    #[test]
+    fn baidu_search_provider_aliases_parse() {
+        assert_eq!(SearchProvider::parse("baidu"), Some(SearchProvider::Baidu));
+        assert_eq!(
+            SearchProvider::parse("baidu-search"),
+            Some(SearchProvider::Baidu)
+        );
+        assert_eq!(
+            SearchProvider::parse("baidu_ai_search"),
+            Some(SearchProvider::Baidu)
+        );
+    }
+
+    #[test]
+    fn search_provider_resolution_reports_default_source() {
+        let _guard = lock_test_env();
+        let prev = env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { env::remove_var("DEEPSEEK_SEARCH_PROVIDER") };
+
+        let resolution = Config::default().search_provider_resolution();
+
+        unsafe { EnvGuard::restore_var("DEEPSEEK_SEARCH_PROVIDER", prev) };
+        assert_eq!(resolution.provider, SearchProvider::DuckDuckGo);
+        assert_eq!(resolution.source, SearchProviderSource::Default);
+    }
+
+    #[test]
+    fn search_provider_resolution_reports_config_source() {
+        let _guard = lock_test_env();
+        let prev = env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { env::remove_var("DEEPSEEK_SEARCH_PROVIDER") };
+        let config: Config = toml::from_str(
+            r#"
+            [search]
+            provider = "tavily"
+            "#,
+        )
+        .expect("search config");
+
+        let resolution = config.search_provider_resolution();
+
+        unsafe { EnvGuard::restore_var("DEEPSEEK_SEARCH_PROVIDER", prev) };
+        assert_eq!(resolution.provider, SearchProvider::Tavily);
+        assert_eq!(resolution.source, SearchProviderSource::Config);
+    }
+
+    #[test]
+    fn search_provider_resolution_reports_env_override_source() {
+        let _guard = lock_test_env();
+        let prev = env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { env::set_var("DEEPSEEK_SEARCH_PROVIDER", "bocha") };
+        let config: Config = toml::from_str(
+            r#"
+            [search]
+            provider = "duckduckgo"
+            "#,
+        )
+        .expect("search config");
+
+        let resolution = config.search_provider_resolution();
+
+        unsafe { EnvGuard::restore_var("DEEPSEEK_SEARCH_PROVIDER", prev) };
+        assert_eq!(resolution.provider, SearchProvider::Bocha);
+        assert_eq!(resolution.source, SearchProviderSource::EnvOverride);
+    }
+
+    #[test]
+    fn search_provider_env_override_accepts_baidu() {
+        let _guard = lock_test_env();
+        let prev = env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { env::set_var("DEEPSEEK_SEARCH_PROVIDER", "baidu") };
+        let config: Config = toml::from_str(
+            r#"
+            [search]
+            provider = "duckduckgo"
+            "#,
+        )
+        .expect("search config");
+
+        let resolution = config.search_provider_resolution();
+
+        unsafe { EnvGuard::restore_var("DEEPSEEK_SEARCH_PROVIDER", prev) };
+        assert_eq!(resolution.provider, SearchProvider::Baidu);
+        assert_eq!(resolution.source, SearchProviderSource::EnvOverride);
+    }
+
+    #[test]
+    fn apply_env_overrides_sets_search_api_key() {
+        let _guard = lock_test_env();
+        let prev = env::var_os("DEEPSEEK_SEARCH_API_KEY");
+        unsafe { env::set_var("DEEPSEEK_SEARCH_API_KEY", "search-env-key") };
+        let mut config = Config::default();
+
+        apply_env_overrides(&mut config);
+
+        unsafe { EnvGuard::restore_var("DEEPSEEK_SEARCH_API_KEY", prev) };
+        assert_eq!(
+            config.search.and_then(|search| search.api_key),
+            Some("search-env-key".to_string())
+        );
+    }
+
+    #[test]
+    fn search_provider_resolution_ignores_invalid_env_override() {
+        let _guard = lock_test_env();
+        let prev = env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { env::set_var("DEEPSEEK_SEARCH_PROVIDER", "not-a-provider") };
+        let config: Config = toml::from_str(
+            r#"
+            [search]
+            provider = "tavily"
+            "#,
+        )
+        .expect("search config");
+
+        let resolution = config.search_provider_resolution();
+
+        unsafe { EnvGuard::restore_var("DEEPSEEK_SEARCH_PROVIDER", prev) };
+        assert_eq!(resolution.provider, SearchProvider::Tavily);
+        assert_eq!(resolution.source, SearchProviderSource::Config);
+    }
+
     struct EnvGuard {
         home: Option<OsString>,
         userprofile: Option<OsString>,
@@ -3708,6 +4578,9 @@ mod tests {
         deepseek_http_headers: Option<OsString>,
         deepseek_model: Option<OsString>,
         deepseek_default_text_model: Option<OsString>,
+        codewhale_provider: Option<OsString>,
+        codewhale_model: Option<OsString>,
+        codewhale_base_url: Option<OsString>,
         nvidia_api_key: Option<OsString>,
         nvidia_nim_api_key: Option<OsString>,
         nim_base_url: Option<OsString>,
@@ -3731,10 +4604,26 @@ mod tests {
         wanjie_maas_model: Option<OsString>,
         openrouter_api_key: Option<OsString>,
         openrouter_base_url: Option<OsString>,
+        xiaomi_mimo_api_key: Option<OsString>,
+        mimo_api_key: Option<OsString>,
+        xiaomi_mimo_base_url: Option<OsString>,
+        mimo_base_url: Option<OsString>,
+        xiaomi_mimo_model: Option<OsString>,
+        mimo_model: Option<OsString>,
         novita_api_key: Option<OsString>,
         novita_base_url: Option<OsString>,
         fireworks_api_key: Option<OsString>,
         fireworks_base_url: Option<OsString>,
+        moonshot_api_key: Option<OsString>,
+        moonshot_base_url: Option<OsString>,
+        moonshot_model: Option<OsString>,
+        kimi_api_key: Option<OsString>,
+        kimi_base_url: Option<OsString>,
+        kimi_model: Option<OsString>,
+        kimi_model_name: Option<OsString>,
+        kimi_share_dir: Option<OsString>,
+        kimi_code_oauth_host: Option<OsString>,
+        kimi_oauth_host: Option<OsString>,
         sglang_api_key: Option<OsString>,
         sglang_base_url: Option<OsString>,
         sglang_model: Option<OsString>,
@@ -3760,6 +4649,9 @@ mod tests {
             let http_headers_prev = env::var_os("DEEPSEEK_HTTP_HEADERS");
             let model_prev = env::var_os("DEEPSEEK_MODEL");
             let default_text_model_prev = env::var_os("DEEPSEEK_DEFAULT_TEXT_MODEL");
+            let codewhale_provider_prev = env::var_os("CODEWHALE_PROVIDER");
+            let codewhale_model_prev = env::var_os("CODEWHALE_MODEL");
+            let codewhale_base_url_prev = env::var_os("CODEWHALE_BASE_URL");
             let nvidia_api_key_prev = env::var_os("NVIDIA_API_KEY");
             let nvidia_nim_api_key_prev = env::var_os("NVIDIA_NIM_API_KEY");
             let nim_base_url_prev = env::var_os("NIM_BASE_URL");
@@ -3783,10 +4675,26 @@ mod tests {
             let wanjie_maas_model_prev = env::var_os("WANJIE_MAAS_MODEL");
             let openrouter_api_key_prev = env::var_os("OPENROUTER_API_KEY");
             let openrouter_base_url_prev = env::var_os("OPENROUTER_BASE_URL");
+            let xiaomi_mimo_api_key_prev = env::var_os("XIAOMI_MIMO_API_KEY");
+            let mimo_api_key_prev = env::var_os("MIMO_API_KEY");
+            let xiaomi_mimo_base_url_prev = env::var_os("XIAOMI_MIMO_BASE_URL");
+            let mimo_base_url_prev = env::var_os("MIMO_BASE_URL");
+            let xiaomi_mimo_model_prev = env::var_os("XIAOMI_MIMO_MODEL");
+            let mimo_model_prev = env::var_os("MIMO_MODEL");
             let novita_api_key_prev = env::var_os("NOVITA_API_KEY");
             let novita_base_url_prev = env::var_os("NOVITA_BASE_URL");
             let fireworks_api_key_prev = env::var_os("FIREWORKS_API_KEY");
             let fireworks_base_url_prev = env::var_os("FIREWORKS_BASE_URL");
+            let moonshot_api_key_prev = env::var_os("MOONSHOT_API_KEY");
+            let moonshot_base_url_prev = env::var_os("MOONSHOT_BASE_URL");
+            let moonshot_model_prev = env::var_os("MOONSHOT_MODEL");
+            let kimi_api_key_prev = env::var_os("KIMI_API_KEY");
+            let kimi_base_url_prev = env::var_os("KIMI_BASE_URL");
+            let kimi_model_prev = env::var_os("KIMI_MODEL");
+            let kimi_model_name_prev = env::var_os("KIMI_MODEL_NAME");
+            let kimi_share_dir_prev = env::var_os("KIMI_SHARE_DIR");
+            let kimi_code_oauth_host_prev = env::var_os("KIMI_CODE_OAUTH_HOST");
+            let kimi_oauth_host_prev = env::var_os("KIMI_OAUTH_HOST");
             let sglang_api_key_prev = env::var_os("SGLANG_API_KEY");
             let sglang_base_url_prev = env::var_os("SGLANG_BASE_URL");
             let sglang_model_prev = env::var_os("SGLANG_MODEL");
@@ -3807,6 +4715,9 @@ mod tests {
                 env::remove_var("DEEPSEEK_HTTP_HEADERS");
                 env::remove_var("DEEPSEEK_MODEL");
                 env::remove_var("DEEPSEEK_DEFAULT_TEXT_MODEL");
+                env::remove_var("CODEWHALE_PROVIDER");
+                env::remove_var("CODEWHALE_MODEL");
+                env::remove_var("CODEWHALE_BASE_URL");
                 env::remove_var("NVIDIA_API_KEY");
                 env::remove_var("NVIDIA_NIM_API_KEY");
                 env::remove_var("NIM_BASE_URL");
@@ -3830,10 +4741,26 @@ mod tests {
                 env::remove_var("WANJIE_MAAS_MODEL");
                 env::remove_var("OPENROUTER_API_KEY");
                 env::remove_var("OPENROUTER_BASE_URL");
+                env::remove_var("XIAOMI_MIMO_API_KEY");
+                env::remove_var("MIMO_API_KEY");
+                env::remove_var("XIAOMI_MIMO_BASE_URL");
+                env::remove_var("MIMO_BASE_URL");
+                env::remove_var("XIAOMI_MIMO_MODEL");
+                env::remove_var("MIMO_MODEL");
                 env::remove_var("NOVITA_API_KEY");
                 env::remove_var("NOVITA_BASE_URL");
                 env::remove_var("FIREWORKS_API_KEY");
                 env::remove_var("FIREWORKS_BASE_URL");
+                env::remove_var("MOONSHOT_API_KEY");
+                env::remove_var("MOONSHOT_BASE_URL");
+                env::remove_var("MOONSHOT_MODEL");
+                env::remove_var("KIMI_API_KEY");
+                env::remove_var("KIMI_BASE_URL");
+                env::remove_var("KIMI_MODEL");
+                env::remove_var("KIMI_MODEL_NAME");
+                env::remove_var("KIMI_SHARE_DIR");
+                env::remove_var("KIMI_CODE_OAUTH_HOST");
+                env::remove_var("KIMI_OAUTH_HOST");
                 env::remove_var("SGLANG_API_KEY");
                 env::remove_var("SGLANG_BASE_URL");
                 env::remove_var("SGLANG_MODEL");
@@ -3854,6 +4781,9 @@ mod tests {
                 deepseek_http_headers: http_headers_prev,
                 deepseek_model: model_prev,
                 deepseek_default_text_model: default_text_model_prev,
+                codewhale_provider: codewhale_provider_prev,
+                codewhale_model: codewhale_model_prev,
+                codewhale_base_url: codewhale_base_url_prev,
                 nvidia_api_key: nvidia_api_key_prev,
                 nvidia_nim_api_key: nvidia_nim_api_key_prev,
                 nim_base_url: nim_base_url_prev,
@@ -3877,10 +4807,26 @@ mod tests {
                 wanjie_maas_model: wanjie_maas_model_prev,
                 openrouter_api_key: openrouter_api_key_prev,
                 openrouter_base_url: openrouter_base_url_prev,
+                xiaomi_mimo_api_key: xiaomi_mimo_api_key_prev,
+                mimo_api_key: mimo_api_key_prev,
+                xiaomi_mimo_base_url: xiaomi_mimo_base_url_prev,
+                mimo_base_url: mimo_base_url_prev,
+                xiaomi_mimo_model: xiaomi_mimo_model_prev,
+                mimo_model: mimo_model_prev,
                 novita_api_key: novita_api_key_prev,
                 novita_base_url: novita_base_url_prev,
                 fireworks_api_key: fireworks_api_key_prev,
                 fireworks_base_url: fireworks_base_url_prev,
+                moonshot_api_key: moonshot_api_key_prev,
+                moonshot_base_url: moonshot_base_url_prev,
+                moonshot_model: moonshot_model_prev,
+                kimi_api_key: kimi_api_key_prev,
+                kimi_base_url: kimi_base_url_prev,
+                kimi_model: kimi_model_prev,
+                kimi_model_name: kimi_model_name_prev,
+                kimi_share_dir: kimi_share_dir_prev,
+                kimi_code_oauth_host: kimi_code_oauth_host_prev,
+                kimi_oauth_host: kimi_oauth_host_prev,
                 sglang_api_key: sglang_api_key_prev,
                 sglang_base_url: sglang_base_url_prev,
                 sglang_model: sglang_model_prev,
@@ -3910,6 +4856,9 @@ mod tests {
                     "DEEPSEEK_DEFAULT_TEXT_MODEL",
                     self.deepseek_default_text_model.take(),
                 );
+                Self::restore_var("CODEWHALE_PROVIDER", self.codewhale_provider.take());
+                Self::restore_var("CODEWHALE_MODEL", self.codewhale_model.take());
+                Self::restore_var("CODEWHALE_BASE_URL", self.codewhale_base_url.take());
                 Self::restore_var("NVIDIA_API_KEY", self.nvidia_api_key.take());
                 Self::restore_var("NVIDIA_NIM_API_KEY", self.nvidia_nim_api_key.take());
                 Self::restore_var("NIM_BASE_URL", self.nim_base_url.take());
@@ -3933,10 +4882,26 @@ mod tests {
                 Self::restore_var("WANJIE_MAAS_MODEL", self.wanjie_maas_model.take());
                 Self::restore_var("OPENROUTER_API_KEY", self.openrouter_api_key.take());
                 Self::restore_var("OPENROUTER_BASE_URL", self.openrouter_base_url.take());
+                Self::restore_var("XIAOMI_MIMO_API_KEY", self.xiaomi_mimo_api_key.take());
+                Self::restore_var("MIMO_API_KEY", self.mimo_api_key.take());
+                Self::restore_var("XIAOMI_MIMO_BASE_URL", self.xiaomi_mimo_base_url.take());
+                Self::restore_var("MIMO_BASE_URL", self.mimo_base_url.take());
+                Self::restore_var("XIAOMI_MIMO_MODEL", self.xiaomi_mimo_model.take());
+                Self::restore_var("MIMO_MODEL", self.mimo_model.take());
                 Self::restore_var("NOVITA_API_KEY", self.novita_api_key.take());
                 Self::restore_var("NOVITA_BASE_URL", self.novita_base_url.take());
                 Self::restore_var("FIREWORKS_API_KEY", self.fireworks_api_key.take());
                 Self::restore_var("FIREWORKS_BASE_URL", self.fireworks_base_url.take());
+                Self::restore_var("MOONSHOT_API_KEY", self.moonshot_api_key.take());
+                Self::restore_var("MOONSHOT_BASE_URL", self.moonshot_base_url.take());
+                Self::restore_var("MOONSHOT_MODEL", self.moonshot_model.take());
+                Self::restore_var("KIMI_API_KEY", self.kimi_api_key.take());
+                Self::restore_var("KIMI_BASE_URL", self.kimi_base_url.take());
+                Self::restore_var("KIMI_MODEL", self.kimi_model.take());
+                Self::restore_var("KIMI_MODEL_NAME", self.kimi_model_name.take());
+                Self::restore_var("KIMI_SHARE_DIR", self.kimi_share_dir.take());
+                Self::restore_var("KIMI_CODE_OAUTH_HOST", self.kimi_code_oauth_host.take());
+                Self::restore_var("KIMI_OAUTH_HOST", self.kimi_oauth_host.take());
                 Self::restore_var("SGLANG_API_KEY", self.sglang_api_key.take());
                 Self::restore_var("SGLANG_BASE_URL", self.sglang_base_url.take());
                 Self::restore_var("SGLANG_MODEL", self.sglang_model.take());
@@ -4830,9 +5795,17 @@ api_key = "old-openrouter-key"
         );
     }
 
+    #[test]
+    fn model_completion_names_for_moonshot_excludes_oauth_only_kimi_code_model() {
+        assert_eq!(
+            model_completion_names_for_provider(ApiProvider::Moonshot),
+            vec![DEFAULT_MOONSHOT_MODEL]
+        );
+    }
+
     #[test]
     fn normalize_model_name_rejects_invalid_or_non_deepseek_ids() {
-        assert!(normalize_model_name("gpt-4o").is_none());
+        assert!(normalize_model_name("qwen3-coder").is_none());
         assert!(normalize_model_name("codewhale v4").is_none());
         assert!(normalize_model_name("").is_none());
     }
@@ -5257,6 +6230,54 @@ http_headers = { "X-Model-Provider-Id" = "from-file" }
         Ok(())
     }
 
+    #[test]
+    fn xiaomi_mimo_provider_uses_documented_defaults() -> Result<()> {
+        let config = Config {
+            provider: Some("xiaomi-mimo".to_string()),
+            ..Default::default()
+        };
+
+        config.validate()?;
+        assert_eq!(config.api_provider(), ApiProvider::XiaomiMimo);
+        assert_eq!(config.default_model(), DEFAULT_XIAOMI_MIMO_MODEL);
+        assert_eq!(config.deepseek_base_url(), DEFAULT_XIAOMI_MIMO_BASE_URL);
+        Ok(())
+    }
+
+    #[test]
+    fn xiaomi_mimo_env_overrides_provider_base_url_model_and_key() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-xiaomi-mimo-env-test-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        // Safety: test-only environment mutation guarded by a global mutex.
+        unsafe {
+            env::set_var("DEEPSEEK_PROVIDER", "mimo");
+            env::set_var("MIMO_API_KEY", "mimo-env-key");
+            env::set_var("MIMO_BASE_URL", "https://mimo-gateway.example/v1");
+            env::set_var("MIMO_MODEL", "mimo-v2.5");
+        }
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::XiaomiMimo);
+        assert_eq!(config.deepseek_api_key()?, "mimo-env-key");
+        assert_eq!(
+            config.deepseek_base_url(),
+            "https://mimo-gateway.example/v1"
+        );
+        assert_eq!(config.default_model(), "mimo-v2.5");
+        Ok(())
+    }
+
     #[test]
     fn atlascloud_provider_uses_documented_defaults() -> Result<()> {
         let config = Config {
@@ -5752,6 +6773,35 @@ model = "qwen2.5-coder:7b"
         Ok(())
     }
 
+    #[test]
+    fn vllm_env_resolves_reported_lan_http_endpoint_and_model() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-vllm-lan-http-test-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        // Safety: test-only environment mutation guarded by a global mutex.
+        unsafe {
+            env::set_var("DEEPSEEK_PROVIDER", "vllm");
+            env::set_var("VLLM_BASE_URL", "http://192.168.0.110:8000/v1");
+            env::set_var("DEEPSEEK_MODEL", "deepseek-v4-flash");
+        }
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Vllm);
+        assert_eq!(config.deepseek_base_url(), "http://192.168.0.110:8000/v1");
+        assert_eq!(config.default_model(), "deepseek-v4-flash");
+        Ok(())
+    }
+
     #[test]
     fn ollama_env_overrides_base_url_and_model() -> Result<()> {
         let _lock = lock_test_env();
@@ -5965,6 +7015,297 @@ api_key = "novita-table-key"
         Ok(())
     }
 
+    #[test]
+    fn moonshot_kimi_oauth_reads_fresh_cli_credential() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-kimi-oauth-key-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        let kimi_share_dir = temp_root.join(".kimi");
+        let credential_dir = kimi_share_dir.join("credentials");
+        fs::create_dir_all(&credential_dir)?;
+        unsafe { env::set_var("KIMI_SHARE_DIR", &kimi_share_dir) };
+
+        let expires_at = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_secs_f64()
+            + 3600.0;
+        let credential = json!({
+            "access_token": "fresh-oauth-token",
+            "refresh_token": "refresh-token",
+            "expires_at": expires_at,
+            "scope": "openid profile email",
+            "token_type": "Bearer",
+        });
+        fs::write(
+            credential_dir.join(KIMI_CODE_CREDENTIAL_FILE),
+            serde_json::to_string(&credential)?,
+        )?;
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        ensure_parent_dir(&config_path)?;
+        fs::write(
+            &config_path,
+            r#"provider = "moonshot"
+
+[providers.moonshot]
+auth_mode = "kimi_oauth"
+api_key = "stale-api-key"
+"#,
+        )?;
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Moonshot);
+        assert_eq!(config.deepseek_base_url(), DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(config.default_model(), DEFAULT_KIMI_CODE_MODEL);
+        assert_eq!(config.deepseek_api_key()?, "fresh-oauth-token");
+        assert!(has_api_key_for(&config, ApiProvider::Moonshot));
+        Ok(())
+    }
+
+    #[test]
+    fn moonshot_kimi_code_api_key_uses_coding_model() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-kimi-code-key-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        ensure_parent_dir(&config_path)?;
+        fs::write(
+            &config_path,
+            r#"provider = "moonshot"
+
+[providers.moonshot]
+api_key = "kimi-code-key"
+base_url = "https://api.kimi.com/coding/v1"
+"#,
+        )?;
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Moonshot);
+        assert_eq!(config.deepseek_base_url(), DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(config.default_model(), DEFAULT_KIMI_CODE_MODEL);
+        assert_eq!(config.deepseek_api_key()?, "kimi-code-key");
+        assert!(has_api_key_for(&config, ApiProvider::Moonshot));
+        Ok(())
+    }
+
+    /// Env-var-only path: `CODEWHALE_BASE_URL=https://api.kimi.com/coding/v1`
+    /// combined with `CODEWHALE_PROVIDER=moonshot` must trigger Kimi Code
+    /// model selection even when the TOML has no `base_url`.
+    #[test]
+    fn moonshot_kimi_code_env_base_url_selects_coding_model() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-kimi-code-env-url-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        ensure_parent_dir(&config_path)?;
+        fs::write(
+            &config_path,
+            r#"[providers.moonshot]
+api_key = "kimi-code-env-key"
+"#,
+        )?;
+        // Safety: test-only env mutation guarded by lock_test_env().
+        unsafe {
+            env::set_var("CODEWHALE_PROVIDER", "moonshot");
+            env::set_var("CODEWHALE_BASE_URL", "https://api.kimi.com/coding/v1");
+        }
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Moonshot);
+        assert_eq!(config.deepseek_base_url(), DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(config.default_model(), DEFAULT_KIMI_CODE_MODEL);
+        assert_eq!(config.deepseek_api_key()?, "kimi-code-env-key");
+        assert!(has_api_key_for(&config, ApiProvider::Moonshot));
+        Ok(())
+    }
+
+    /// Regression for issue #2160: a stale root `default_text_model` carried
+    /// over from a DeepSeek setup must not steer the Kimi Code endpoint to
+    /// `deepseek-v4-pro`. The user-facing trigger here is the legacy
+    /// `DEEPSEEK_PROVIDER` env var (still produced by the `codewhale
+    /// --provider moonshot` dispatcher for compat); the test also has a
+    /// `CODEWHALE_PROVIDER` twin below for the public env path.
+    #[test]
+    fn moonshot_kimi_code_model_overrides_root_deepseek_default() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-kimi-code-root-model-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        ensure_parent_dir(&config_path)?;
+        fs::write(
+            &config_path,
+            r#"provider = "deepseek"
+default_text_model = "deepseek-v4-pro"
+
+[providers.moonshot]
+api_key = "kimi-code-key"
+base_url = "https://api.kimi.com/coding/v1"
+"#,
+        )?;
+        // Safety: test-only env mutation guarded by lock_test_env().
+        unsafe { env::set_var("DEEPSEEK_PROVIDER", "moonshot") };
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Moonshot);
+        assert_eq!(config.deepseek_base_url(), DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(config.default_model(), DEFAULT_KIMI_CODE_MODEL);
+        Ok(())
+    }
+
+    /// Same regression as above, but driven by the public `CODEWHALE_PROVIDER`
+    /// env var. Documents the recommended user-facing setup path: never
+    /// `DEEPSEEK_PROVIDER=moonshot`, always `CODEWHALE_PROVIDER=moonshot`
+    /// (or `codewhale --provider moonshot`, which also resolves through
+    /// this code path internally).
+    #[test]
+    fn moonshot_kimi_code_model_resolves_via_codewhale_provider_env() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-kimi-code-cw-env-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        ensure_parent_dir(&config_path)?;
+        fs::write(
+            &config_path,
+            r#"provider = "deepseek"
+default_text_model = "deepseek-v4-pro"
+
+[providers.moonshot]
+api_key = "kimi-code-key"
+base_url = "https://api.kimi.com/coding/v1"
+"#,
+        )?;
+        // Safety: test-only env mutation guarded by lock_test_env().
+        unsafe { env::set_var("CODEWHALE_PROVIDER", "moonshot") };
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Moonshot);
+        assert_eq!(config.deepseek_base_url(), DEFAULT_KIMI_CODE_BASE_URL);
+        assert_eq!(config.default_model(), DEFAULT_KIMI_CODE_MODEL);
+        Ok(())
+    }
+
+    /// `CODEWHALE_PROVIDER` wins when both it and the legacy
+    /// `DEEPSEEK_PROVIDER` are set, so a user adding the new alias to their
+    /// shell isn't surprised by a stale legacy export.
+    #[test]
+    fn codewhale_provider_env_takes_precedence_over_deepseek_provider() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-cw-vs-ds-provider-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        ensure_parent_dir(&config_path)?;
+        fs::write(&config_path, "provider = \"deepseek\"\n")?;
+        // Safety: test-only env mutation guarded by lock_test_env().
+        unsafe {
+            env::set_var("CODEWHALE_PROVIDER", "moonshot");
+            env::set_var("DEEPSEEK_PROVIDER", "openrouter");
+        }
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Moonshot);
+        Ok(())
+    }
+
+    /// Moonshot Platform path: when [providers.moonshot] is empty (or
+    /// missing) and no Kimi Code endpoint is configured, the resolver
+    /// defaults to the Moonshot Platform base URL and the `kimi-k2.6`
+    /// model. This is the "I have a Moonshot Platform API key, not a
+    /// Kimi Code plan key" path.
+    #[test]
+    fn moonshot_platform_defaults_to_kimi_k26() -> Result<()> {
+        let _lock = lock_test_env();
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let temp_root = env::temp_dir().join(format!(
+            "codewhale-tui-moonshot-platform-{}-{}",
+            std::process::id(),
+            nanos
+        ));
+        fs::create_dir_all(&temp_root)?;
+        let _guard = EnvGuard::new(&temp_root);
+
+        let config_path = temp_root.join(".deepseek").join("config.toml");
+        ensure_parent_dir(&config_path)?;
+        fs::write(
+            &config_path,
+            r#"provider = "moonshot"
+
+[providers.moonshot]
+api_key = "moonshot-platform-key"
+"#,
+        )?;
+
+        let config = Config::load(None, None)?;
+        assert_eq!(config.api_provider(), ApiProvider::Moonshot);
+        assert_eq!(config.deepseek_base_url(), DEFAULT_MOONSHOT_BASE_URL);
+        assert_eq!(config.default_model(), DEFAULT_MOONSHOT_MODEL);
+        assert_eq!(config.deepseek_api_key()?, "moonshot-platform-key");
+        Ok(())
+    }
+
     #[test]
     fn has_api_key_for_detects_env_and_config_per_provider() -> Result<()> {
         let _lock = lock_test_env();
@@ -5984,6 +7325,7 @@ api_key = "novita-table-key"
         assert!(!has_api_key_for(&config, ApiProvider::Openai));
         assert!(!has_api_key_for(&config, ApiProvider::WanjieArk));
         assert!(!has_api_key_for(&config, ApiProvider::Openrouter));
+        assert!(!has_api_key_for(&config, ApiProvider::XiaomiMimo));
         assert!(
             has_api_key_for(&config, ApiProvider::Sglang),
             "SGLang is self-hosted and does not require a key by default"
@@ -5998,10 +7340,12 @@ api_key = "novita-table-key"
             env::set_var("OPENROUTER_API_KEY", "or-env");
             env::set_var("OPENAI_API_KEY", "openai-env");
             env::set_var("WANJIE_API_KEY", "wanjie-env");
+            env::set_var("MIMO_API_KEY", "mimo-env");
         }
         assert!(has_api_key_for(&config, ApiProvider::Openai));
         assert!(has_api_key_for(&config, ApiProvider::WanjieArk));
         assert!(has_api_key_for(&config, ApiProvider::Openrouter));
+        assert!(has_api_key_for(&config, ApiProvider::XiaomiMimo));
         assert!(!has_api_key_for(&config, ApiProvider::Novita));
 
         // Safety: test-only environment mutation guarded by a global mutex.
@@ -6009,14 +7353,17 @@ api_key = "novita-table-key"
             env::remove_var("OPENROUTER_API_KEY");
             env::remove_var("OPENAI_API_KEY");
             env::remove_var("WANJIE_API_KEY");
+            env::remove_var("MIMO_API_KEY");
         }
         let mut providers = ProvidersConfig::default();
         providers.openai.api_key = Some("file-openai".to_string());
         providers.wanjie_ark.api_key = Some("file-wanjie".to_string());
+        providers.xiaomi_mimo.api_key = Some("file-mimo".to_string());
         providers.novita.api_key = Some("file-novita".to_string());
         config.providers = Some(providers);
         assert!(has_api_key_for(&config, ApiProvider::Openai));
         assert!(has_api_key_for(&config, ApiProvider::WanjieArk));
+        assert!(has_api_key_for(&config, ApiProvider::XiaomiMimo));
         assert!(has_api_key_for(&config, ApiProvider::Novita));
         assert!(!has_api_key_for(&config, ApiProvider::Openrouter));
         Ok(())
@@ -6109,6 +7456,7 @@ api_key = "novita-table-key"
         save_api_key_for(ApiProvider::Openai, "openai-saved-key")?;
         save_api_key_for(ApiProvider::WanjieArk, "wanjie-saved-key")?;
         save_api_key_for(ApiProvider::Fireworks, "fireworks-saved-key")?;
+        save_api_key_for(ApiProvider::XiaomiMimo, "mimo-saved-key")?;
         save_api_key_for(ApiProvider::Sglang, "sglang-saved-key")?;
         let contents = fs::read_to_string(&path)?;
         let parsed: toml::Value = toml::from_str(&contents)?;
@@ -6136,6 +7484,14 @@ api_key = "novita-table-key"
                 .and_then(toml::Value::as_str),
             Some("fireworks-saved-key")
         );
+        assert_eq!(
+            parsed
+                .get("providers")
+                .and_then(|p| p.get("xiaomi_mimo"))
+                .and_then(|t| t.get("api_key"))
+                .and_then(toml::Value::as_str),
+            Some("mimo-saved-key")
+        );
         assert_eq!(
             parsed
                 .get("providers")
@@ -6371,6 +7727,19 @@ model = "deepseek-ai/deepseek-v4-pro"
         );
     }
 
+    #[test]
+    fn provider_capability_xiaomi_mimo_has_thinking_no_cache() {
+        let cap = provider_capability(ApiProvider::XiaomiMimo, DEFAULT_XIAOMI_MIMO_MODEL);
+        assert_eq!(cap.context_window, 1_000_000);
+        assert_eq!(cap.max_output, 128_000);
+        assert!(cap.thinking_supported);
+        assert!(!cap.cache_telemetry_supported);
+        assert_eq!(
+            cap.request_payload_mode,
+            RequestPayloadMode::ChatCompletions
+        );
+    }
+
     #[test]
     fn provider_capability_novita_v4_pro_has_thinking_no_cache() {
         let cap = provider_capability(ApiProvider::Novita, DEFAULT_NOVITA_MODEL);
diff --git a/crates/tui/src/config_ui.rs b/crates/tui/src/config_ui.rs
index 7e400496..9cf8ecd2 100644
--- a/crates/tui/src/config_ui.rs
+++ b/crates/tui/src/config_ui.rs
@@ -278,6 +278,7 @@ pub enum StatusItemValue {
     GitBranch,
     LastToolElapsed,
     RateLimit,
+    Tokens,
 }
 
 pub fn parse_mode(arg: Option<&str>) -> Result<ConfigUiMode, String> {
@@ -686,7 +687,11 @@ fn apply_reasoning_effort(
     app.last_effective_reasoning_effort = None;
     app.update_model_compaction_budget();
     if persist {
-        commands::persist_root_string_key("reasoning_effort", effort.as_setting())?;
+        commands::persist_root_string_key(
+            app.config_path.as_deref(),
+            "reasoning_effort",
+            effort.as_setting(),
+        )?;
     }
     config.reasoning_effort = Some(effort.as_setting().to_string());
     Ok(())
@@ -996,6 +1001,7 @@ impl From<StatusItem> for StatusItemValue {
             StatusItem::GitBranch => Self::GitBranch,
             StatusItem::LastToolElapsed => Self::LastToolElapsed,
             StatusItem::RateLimit => Self::RateLimit,
+            StatusItem::Tokens => Self::Tokens,
         }
     }
 }
@@ -1016,6 +1022,7 @@ impl From<StatusItemValue> for StatusItem {
             StatusItemValue::GitBranch => Self::GitBranch,
             StatusItemValue::LastToolElapsed => Self::LastToolElapsed,
             StatusItemValue::RateLimit => Self::RateLimit,
+            StatusItemValue::Tokens => Self::Tokens,
         }
     }
 }
diff --git a/crates/tui/src/core/capacity_memory.rs b/crates/tui/src/core/capacity_memory.rs
index f41bd48a..0d22e4df 100644
--- a/crates/tui/src/core/capacity_memory.rs
+++ b/crates/tui/src/core/capacity_memory.rs
@@ -56,14 +56,20 @@ fn capacity_memory_dirs() -> Vec<PathBuf> {
 
     let mut dirs = Vec::new();
     if let Some(home) = dirs::home_dir() {
+        // Prefer .codewhale, fall back to .deepseek
+        let primary = home.join(".codewhale").join("memory");
+        if primary.exists() {
+            dirs.push(primary);
+        }
         dirs.push(home.join(".deepseek").join("memory"));
     }
 
-    let cwd = std::env::current_dir()
-        .unwrap_or_else(|_| PathBuf::from("."))
-        .join(".deepseek")
-        .join("memory");
-    dirs.push(cwd);
+    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    let primary_cwd = cwd.join(".codewhale").join("memory");
+    if primary_cwd.exists() {
+        dirs.push(primary_cwd);
+    }
+    dirs.push(cwd.join(".deepseek").join("memory"));
 
     dirs.dedup();
     dirs
diff --git a/crates/tui/src/core/engine.rs b/crates/tui/src/core/engine.rs
index 202cd164..6e1d8966 100644
--- a/crates/tui/src/core/engine.rs
+++ b/crates/tui/src/core/engine.rs
@@ -7,12 +7,12 @@
 //! - Proper cancellation support
 //! - Tool execution orchestration
 
-use std::collections::HashMap;
 use std::collections::hash_map::DefaultHasher;
+use std::collections::{HashMap, HashSet};
 use std::hash::{Hash, Hasher};
 use std::path::PathBuf;
 use std::sync::{Arc, Mutex as StdMutex};
-use std::time::{Duration, Instant};
+use std::time::{Duration, Instant, SystemTime};
 
 use anyhow::Result;
 use futures_util::StreamExt;
@@ -41,7 +41,9 @@ use crate::models::{
     MessageRequest, StreamEvent, SystemPrompt, Tool, Usage,
 };
 use crate::prompts;
+use crate::purge::{emit_purge_completed, emit_purge_failed, emit_purge_started, run_purge};
 use crate::seam_manager::{SeamConfig, SeamManager};
+use crate::tools::goal::{SharedGoalState, new_shared_goal_state};
 use crate::tools::plan::{SharedPlanState, new_shared_plan_state};
 use crate::tools::shell::{SharedShellManager, new_shared_shell_manager};
 use crate::tools::spec::RuntimeToolServices;
@@ -90,15 +92,22 @@ pub struct EngineConfig {
     pub mcp_config_path: PathBuf,
     /// Directory containing discoverable skills.
     pub skills_dir: PathBuf,
-    /// Additional instruction files concatenated into the system
-    /// prompt (#454). Loaded in declared order from the user's
-    /// `instructions = [...]` config (or the per-project override).
-    /// Resolved via `expand_path` so `~` works.
-    pub instructions: Vec<PathBuf>,
+    /// Sources injected as `<instructions source="…">` blocks in the system
+    /// prompt (#454). Each entry is either a disk path (read at render time)
+    /// or an inline string. Loaded in declared order from the user's
+    /// `instructions = [...]` config or constructed by embedders.
+    ///
+    /// Generalized from `Vec<PathBuf>` so embedders can inject inline content
+    /// without staging a disk file. `From<PathBuf>` impl keeps existing callers
+    /// working with `.into()` at the call site.
+    pub instructions: Vec<crate::prompts::InstructionSource>,
     pub project_context_pack_enabled: bool,
     /// When true, the model is instructed to respond in the current locale
     /// and a post-hoc translation layer replaces remaining English output.
     pub translation_enabled: bool,
+    /// Whether user-visible transcript rendering shows thinking blocks.
+    /// Prompt assembly uses this to avoid localizing hidden reasoning.
+    pub show_thinking: bool,
     /// Maximum number of assistant steps before stopping.
     pub max_steps: u32,
     /// Maximum number of concurrently active subagents.
@@ -122,6 +131,8 @@ pub struct EngineConfig {
     pub todos: SharedTodoList,
     /// Shared Plan state.
     pub plan_state: SharedPlanState,
+    /// Shared runtime goal state for model-visible goal tools.
+    pub goal_state: SharedGoalState,
     /// Maximum sub-agent recursion depth (default 3). See
     /// `SubAgentRuntime::max_spawn_depth`. Override via
     /// `[runtime] max_spawn_depth = N` in `~/.deepseek/config.toml`.
@@ -152,6 +163,9 @@ pub struct EngineConfig {
     pub memory_path: PathBuf,
     pub vision_config: Option<crate::config::VisionModelConfig>,
     pub goal_objective: Option<String>,
+    /// Tool restriction from custom slash command frontmatter.
+    /// `None` means the current turn may use the normal tool set.
+    pub allowed_tools: Option<Vec<String>>,
     /// Resolved BCP-47 locale tag (e.g. `"en"`, `"zh-Hans"`, `"ja"`)
     /// for the `## Environment` block in the system prompt. The
     /// caller resolves this from `Settings` once at engine
@@ -162,15 +176,24 @@ pub struct EngineConfig {
     pub strict_tool_mode: bool,
     /// Workshop / large-tool-output routing (#548). `None` disables routing.
     pub workshop: Option<crate::tools::large_output_router::WorkshopConfig>,
-    /// Which search backend `web_search` should use. Default: Bing.
+    /// Which search backend `web_search` should use. Default: DuckDuckGo.
     pub search_provider: crate::config::SearchProvider,
-    /// API key for Tavily or Bocha. `None` for Bing or DuckDuckGo.
+    /// API key for Tavily, Bocha, Metaso, or Baidu. `None` for Bing or DuckDuckGo.
+    /// Metaso also falls back to `METASO_API_KEY` env var, then a built-in key.
+    /// Baidu also falls back to `BAIDU_SEARCH_API_KEY`.
     pub search_api_key: Option<String>,
     /// Per-step DeepSeek API timeout for sub-agent `create_message` requests.
     /// Resolved from `[subagents] api_timeout_secs` (clamped to 1..=1800)
     /// once at engine construction, then threaded onto every
     /// `SubAgentRuntime` the engine builds (#1806, #1808).
     pub subagent_api_timeout: Duration,
+    /// Native tools that should stay in the model-visible catalog even when
+    /// they are outside the small default core surface (#2076).
+    pub tools_always_load: HashSet<String>,
+    /// When true and `/usr/bin/bwrap` is present on Linux, route exec_shell
+    /// through bubblewrap instead of relying solely on Landlock (#2184).
+    #[allow(dead_code)] // Wired through ShellManager in follow-up PR
+    pub prefer_bwrap: bool,
 }
 
 impl Default for EngineConfig {
@@ -186,6 +209,7 @@ impl Default for EngineConfig {
             instructions: Vec::new(),
             project_context_pack_enabled: true,
             translation_enabled: false,
+            show_thinking: true,
             max_steps: 100,
             max_subagents: DEFAULT_MAX_SUBAGENTS,
             features: Features::with_defaults(),
@@ -194,6 +218,7 @@ impl Default for EngineConfig {
             capacity: CapacityControllerConfig::default(),
             todos: new_shared_todo_list(),
             plan_state: new_shared_plan_state(),
+            goal_state: new_shared_goal_state(),
             max_spawn_depth: crate::tools::subagent::DEFAULT_MAX_SPAWN_DEPTH,
             network_policy: None,
             snapshots_enabled: true,
@@ -207,6 +232,7 @@ impl Default for EngineConfig {
             vision_config: None,
             strict_tool_mode: false,
             goal_objective: None,
+            allowed_tools: None,
             locale_tag: "en".to_string(),
             workshop: None,
             search_provider: crate::config::SearchProvider::default(),
@@ -214,6 +240,8 @@ impl Default for EngineConfig {
             subagent_api_timeout: Duration::from_secs(
                 crate::config::DEFAULT_SUBAGENT_API_TIMEOUT_SECS,
             ),
+            tools_always_load: HashSet::new(),
+            prefer_bwrap: false,
         }
     }
 }
@@ -331,6 +359,10 @@ pub struct Engine {
     /// Diagnostics collected during the current step's tool calls. Drained
     /// and forwarded as a synthetic user message before the next API call.
     pending_lsp_blocks: Vec<crate::lsp::DiagnosticBlock>,
+    /// Cached SlopLedger gate block keyed by the ledger file's modified time.
+    /// This keeps prompt refreshes cheap while still noticing append/update
+    /// writes from slop ledger tools during the same session.
+    slop_ledger_gate_cache: Option<(Option<SystemTime>, Option<String>)>,
 }
 
 // === Internal tool helpers ===
@@ -368,9 +400,12 @@ impl Engine {
             ApiProvider::Openai => "OPENAI_API_KEY",
             ApiProvider::Atlascloud => "ATLASCLOUD_API_KEY",
             ApiProvider::WanjieArk => "WANJIE_ARK_API_KEY/WANJIE_API_KEY/WANJIE_MAAS_API_KEY",
+            ApiProvider::Volcengine => "VOLCENGINE_API_KEY/VOLCENGINE_ARK_API_KEY/ARK_API_KEY",
             ApiProvider::Openrouter => "OPENROUTER_API_KEY",
+            ApiProvider::XiaomiMimo => "XIAOMI_MIMO_API_KEY/MIMO_API_KEY",
             ApiProvider::Novita => "NOVITA_API_KEY",
             ApiProvider::Fireworks => "FIREWORKS_API_KEY",
+            ApiProvider::Moonshot => "MOONSHOT_API_KEY/KIMI_API_KEY",
             ApiProvider::Sglang => "SGLANG_API_KEY",
             ApiProvider::Vllm => "VLLM_API_KEY",
             ApiProvider::Ollama => "OLLAMA_API_KEY",
@@ -399,6 +434,10 @@ impl Engine {
 
     /// Create a new engine with the given configuration
     pub fn new(config: EngineConfig, api_config: &Config) -> (Self, EngineHandle) {
+        if let Some(objective) = normalized_goal_objective(config.goal_objective.as_deref()) {
+            sync_goal_state_from_host(&config.goal_state, Some(&objective), None, false);
+        }
+
         let (tx_op, rx_op) = mpsc::channel(32);
         let (tx_event, rx_event) = mpsc::channel(256);
         let (tx_approval, rx_approval) = mpsc::channel(64);
@@ -430,6 +469,8 @@ impl Engine {
         // message at request time so file churn does not rewrite this prefix.
         let user_memory_block =
             crate::memory::compose_block(config.memory_enabled, &config.memory_path);
+        let prompt_goal_objective =
+            goal_objective_for_prompt(config.goal_objective.as_deref(), &config.goal_state);
         let system_prompt =
             prompts::system_prompt_for_mode_with_context_skills_session_and_approval(
                 AppMode::Agent,
@@ -439,11 +480,12 @@ impl Engine {
                 Some(&config.instructions),
                 prompts::PromptSessionContext {
                     user_memory_block: user_memory_block.as_deref(),
-                    goal_objective: config.goal_objective.as_deref(),
+                    goal_objective: prompt_goal_objective.as_deref(),
                     project_context_pack_enabled: config.project_context_pack_enabled,
                     locale_tag: &config.locale_tag,
                     translation_enabled: config.translation_enabled,
                     model_id: &config.model,
+                    show_thinking: config.show_thinking,
                 },
                 session.approval_mode,
             );
@@ -563,6 +605,7 @@ impl Engine {
             turn_counter: 0,
             lsp_manager,
             pending_lsp_blocks: Vec::new(),
+            slop_ledger_gate_cache: None,
             workshop_vars,
             sandbox_backend,
         };
@@ -599,6 +642,8 @@ impl Engine {
                     auto_approve,
                     approval_mode,
                     translation_enabled,
+                    show_thinking,
+                    allowed_tools,
                 } => {
                     self.handle_send_message(
                         content,
@@ -613,6 +658,8 @@ impl Engine {
                         auto_approve,
                         approval_mode,
                         translation_enabled,
+                        show_thinking,
+                        allowed_tools,
                     )
                     .await;
                 }
@@ -787,6 +834,9 @@ impl Engine {
                 Op::CompactContext => {
                     self.handle_manual_compaction().await;
                 }
+                Op::PurgeContext => {
+                    self.handle_purge().await;
+                }
                 Op::EditLastTurn { new_message } => {
                     // #383: /edit — remove the last user+assistant exchange
                     // from the session, then re-send with the new content.
@@ -819,6 +869,8 @@ impl Engine {
                         self.session.auto_approve,
                         self.session.approval_mode,
                         self.config.translation_enabled,
+                        self.config.show_thinking,
+                        self.config.allowed_tools.clone(),
                     )
                     .await;
                 }
@@ -907,6 +959,8 @@ impl Engine {
         auto_approve: bool,
         approval_mode: crate::tui::approval::ApprovalMode,
         translation_enabled: bool,
+        show_thinking: bool,
+        allowed_tools: Option<Vec<String>>,
     ) {
         // Reset cancel token for fresh turn (in case previous was cancelled)
         self.reset_cancel_token();
@@ -933,11 +987,17 @@ impl Engine {
         // work on the blocking pool so the async runtime stays responsive;
         // failure is non-fatal (the helper logs at WARN).
         if self.config.snapshots_enabled {
+            // Clone the user prompt now — `content` is moved into
+            // `user_text_message_with_turn_metadata` below, so we need
+            // a copy for both pre- and post-turn snapshot labels. The
+            // label carries a truncated first line so `/restore`
+            // listings are human-readable.
+            let snapshot_prompt = content.clone();
             let pre_workspace = self.session.workspace.clone();
             let pre_seq = self.turn_counter;
             let pre_cap = self.config.snapshots_max_workspace_bytes;
             let _ = tokio::task::spawn_blocking(move || {
-                pre_turn_snapshot(&pre_workspace, pre_seq, pre_cap)
+                pre_turn_snapshot(&pre_workspace, pre_seq, pre_cap, Some(&snapshot_prompt))
             })
             .await;
         }
@@ -948,6 +1008,10 @@ impl Engine {
         // turns (#499).
         crate::retry_status::clear();
 
+        // Clone user prompt for post-turn snapshot label before `content`
+        // is moved into `user_text_message_with_turn_metadata` below.
+        let snapshot_prompt_post = content.clone();
+
         // Check if we have the appropriate client
         if self.deepseek_client.is_none() {
             let message = self
@@ -979,9 +1043,22 @@ impl Engine {
         let user_msg = self.user_text_message_with_turn_metadata(content);
         self.session.add_message(user_msg);
 
+        let previous_goal_objective = self.config.goal_objective.clone();
+
         self.session.model = model;
         self.config.model.clone_from(&self.session.model);
-        self.config.goal_objective = goal_objective;
+        self.config.goal_objective = goal_objective.clone();
+        if normalized_goal_objective(previous_goal_objective.as_deref())
+            != normalized_goal_objective(goal_objective.as_deref())
+        {
+            sync_goal_state_from_host(
+                &self.config.goal_state,
+                normalized_goal_objective(goal_objective.as_deref()).as_deref(),
+                None,
+                false,
+            );
+        }
+        self.config.allowed_tools = allowed_tools;
         self.session.reasoning_effort = reasoning_effort;
         self.session.reasoning_effort_auto = reasoning_effort_auto;
         self.session.auto_model = auto_model;
@@ -990,6 +1067,7 @@ impl Engine {
         self.session.trust_mode = trust_mode;
         self.config.trust_mode = trust_mode;
         self.config.translation_enabled = translation_enabled;
+        self.config.show_thinking = show_thinking;
         self.session.auto_approve = auto_approve;
         self.session.approval_mode = if auto_approve {
             crate::tui::approval::ApprovalMode::Auto
@@ -1114,7 +1192,12 @@ impl Engine {
             Vec::new()
         };
         let tools = tool_registry.as_ref().map(|registry| {
-            build_model_tool_catalog(registry.to_api_tools_with_cache(true), mcp_tools, mode)
+            build_model_tool_catalog(
+                registry.to_api_tools_with_cache(true),
+                mcp_tools,
+                mode,
+                &self.config.tools_always_load,
+            )
         });
 
         // Main turn loop
@@ -1157,11 +1240,18 @@ impl Engine {
         // paste immediately (#234). The git work proceeds on the blocking
         // pool without forcing the engine loop to await it.
         if self.config.snapshots_enabled {
+            // `snapshot_prompt_post` was cloned from `content` above,
+            // before `content` was moved into the session messages.
             let post_workspace = self.session.workspace.clone();
             let post_seq = self.turn_counter;
             let post_cap = self.config.snapshots_max_workspace_bytes;
             crate::utils::spawn_blocking_supervised("post-turn-snapshot", move || {
-                post_turn_snapshot(&post_workspace, post_seq, post_cap);
+                post_turn_snapshot(
+                    &post_workspace,
+                    post_seq,
+                    post_cap,
+                    Some(&snapshot_prompt_post),
+                );
             });
         }
     }
@@ -1268,6 +1358,83 @@ impl Engine {
             .await;
     }
 
+    async fn handle_purge(&mut self) {
+        let zero_usage = Usage {
+            input_tokens: 0,
+            output_tokens: 0,
+            ..Usage::default()
+        };
+        let Some(client) = self.deepseek_client.clone() else {
+            let message = "Purge unavailable: API client not configured".to_string();
+            emit_purge_failed(&self.tx_event, message.clone()).await;
+            let _ = self
+                .tx_event
+                .send(Event::error(ErrorEnvelope::fatal_auth(message.clone())))
+                .await;
+            let _ = self
+                .tx_event
+                .send(Event::TurnComplete {
+                    usage: zero_usage,
+                    status: TurnOutcomeStatus::Failed,
+                    error: Some(message),
+                })
+                .await;
+            return;
+        };
+
+        emit_purge_started(
+            &self.tx_event,
+            "Agent context purge in progress\u{2026}".to_string(),
+        )
+        .await;
+        let messages_before = self.session.messages.len();
+
+        let (status, error) = match run_purge(
+            &client,
+            &self.session.messages,
+            &self.session.model,
+            self.session.reasoning_effort.clone(),
+            effective_max_output_tokens(&self.session.model),
+        )
+        .await
+        {
+            Ok(result) => {
+                let messages_after = result.messages.len();
+                self.session.messages = result.messages;
+                self.emit_session_updated().await;
+
+                let summary = format!(
+                    "Purge complete: {messages_before} → {messages_after} messages \
+                         ({} removed, {} condensed)",
+                    result.removed_count, result.replaced_count,
+                );
+                emit_purge_completed(
+                    &self.tx_event,
+                    messages_before,
+                    messages_after,
+                    result.removed_count,
+                    result.replaced_count,
+                    summary,
+                )
+                .await;
+                (TurnOutcomeStatus::Completed, None)
+            }
+            Err(e) => {
+                emit_purge_failed(&self.tx_event, e.clone()).await;
+                (TurnOutcomeStatus::Failed, Some(e))
+            }
+        };
+
+        let _ = self
+            .tx_event
+            .send(Event::TurnComplete {
+                usage: zero_usage,
+                status,
+                error,
+            })
+            .await;
+    }
+
     fn estimated_input_tokens(&self) -> usize {
         estimate_input_tokens_conservative(
             &self.session.messages,
@@ -1286,15 +1453,8 @@ impl Engine {
         removed
     }
 
-    async fn recover_context_overflow(
-        &mut self,
-        client: &DeepSeekClient,
-        reason: &str,
-        requested_output_tokens: u32,
-    ) -> bool {
-        let Some(target_budget) =
-            context_input_budget(&self.session.model, requested_output_tokens)
-        else {
+    async fn recover_context_overflow(&mut self, client: &DeepSeekClient, reason: &str) -> bool {
+        let Some(target_budget) = context_input_budget(&self.session.model) else {
             return false;
         };
 
@@ -1813,6 +1973,10 @@ impl Engine {
     fn refresh_system_prompt(&mut self, mode: AppMode) {
         let user_memory_block =
             crate::memory::compose_block(self.config.memory_enabled, &self.config.memory_path);
+        let prompt_goal_objective = goal_objective_for_prompt(
+            self.config.goal_objective.as_deref(),
+            &self.config.goal_state,
+        );
         let base = prompts::system_prompt_for_mode_with_context_skills_session_and_approval(
             mode,
             &self.config.workspace,
@@ -1821,16 +1985,29 @@ impl Engine {
             Some(&self.config.instructions),
             prompts::PromptSessionContext {
                 user_memory_block: user_memory_block.as_deref(),
-                goal_objective: self.config.goal_objective.as_deref(),
+                goal_objective: prompt_goal_objective.as_deref(),
                 project_context_pack_enabled: self.config.project_context_pack_enabled,
                 locale_tag: &self.config.locale_tag,
                 translation_enabled: self.config.translation_enabled,
                 model_id: &self.config.model,
+                show_thinking: self.config.show_thinking,
             },
             self.session.approval_mode,
         );
-        let stable_prompt =
+        let mut stable_prompt =
             merge_system_prompts(Some(&base), self.session.compaction_summary_prompt.clone());
+
+        // SlopLedger completion-gate: inject unresolved slop entries into the
+        // system prompt so the agent can autonomously review them before
+        // claiming the task is done (#2127).
+        let gate_block = self.slop_ledger_gate_block();
+        if let Some(ref block) = gate_block {
+            if let Some(SystemPrompt::Text(prompt_text)) = &mut stable_prompt {
+                prompt_text.push_str("\n\n");
+                prompt_text.push_str(block);
+            }
+        }
+
         let stable_hash = system_prompt_hash(stable_prompt.as_ref());
         if self.session.system_prompt_override {
             self.session.last_system_prompt_hash = Some(stable_hash);
@@ -1842,6 +2019,31 @@ impl Engine {
         }
     }
 
+    fn slop_ledger_gate_block(&mut self) -> Option<String> {
+        let modified = crate::slop_ledger::SlopLedger::default_path()
+            .ok()
+            .and_then(|path| std::fs::metadata(path).ok())
+            .and_then(|metadata| metadata.modified().ok());
+
+        if let Some((cached_modified, cached_block)) = &self.slop_ledger_gate_cache
+            && *cached_modified == modified
+        {
+            return cached_block.clone();
+        }
+
+        let loaded = crate::slop_ledger::SlopLedger::load()
+            .ok()
+            .and_then(|ledger| {
+                if ledger.has_open_entries() {
+                    ledger.completion_gate_summary()
+                } else {
+                    None
+                }
+            });
+        self.slop_ledger_gate_cache = Some((modified, loaded.clone()));
+        loaded
+    }
+
     fn merge_compaction_summary(&mut self, summary_prompt: Option<SystemPrompt>) {
         if summary_prompt.is_none() {
             return;
@@ -1880,6 +2082,45 @@ fn system_prompt_hash(prompt: Option<&SystemPrompt>) -> u64 {
     hasher.finish()
 }
 
+fn normalized_goal_objective(value: Option<&str>) -> Option<String> {
+    value
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string)
+}
+
+fn sync_goal_state_from_host(
+    goal_state: &SharedGoalState,
+    objective: Option<&str>,
+    token_budget: Option<u32>,
+    completed: bool,
+) {
+    match goal_state.lock() {
+        Ok(mut state) => state.sync_from_host(objective, token_budget, completed),
+        Err(err) => tracing::warn!("goal state lock poisoned while syncing host goal: {err}"),
+    }
+}
+
+fn goal_objective_for_prompt(
+    configured_goal: Option<&str>,
+    goal_state: &SharedGoalState,
+) -> Option<String> {
+    match goal_state.lock() {
+        Ok(state) => {
+            if state.objective().is_some() {
+                return state.is_active().then(|| {
+                    state
+                        .objective()
+                        .expect("checked goal objective")
+                        .to_string()
+                });
+            }
+        }
+        Err(err) => tracing::warn!("goal state lock poisoned while building prompt: {err}"),
+    }
+    normalized_goal_objective(configured_goal)
+}
+
 /// Spawn the engine in a background task
 pub fn spawn_engine(config: EngineConfig, api_config: &Config) -> EngineHandle {
     let (engine, handle) = Engine::new(config, api_config);
@@ -1970,9 +2211,9 @@ mod handle;
 pub(crate) use context::compact_tool_result_for_context;
 use context::{
     COMPACTION_SUMMARY_MARKER, MAX_CONTEXT_RECOVERY_ATTEMPTS, MIN_RECENT_MESSAGES_TO_KEEP,
-    TURN_MAX_OUTPUT_TOKENS, context_input_budget, effective_max_output_tokens,
-    estimate_input_tokens_conservative, extract_compaction_summary_prompt,
-    is_context_length_error_message, summarize_text, turn_response_headroom_tokens,
+    context_input_budget, effective_max_output_tokens, estimate_input_tokens_conservative,
+    extract_compaction_summary_prompt, is_context_length_error_message, summarize_text,
+    turn_response_headroom_tokens,
 };
 mod dispatch;
 mod loop_guard;
@@ -1983,6 +2224,10 @@ mod tool_execution;
 mod tool_setup;
 mod turn_loop;
 
+pub(crate) fn default_active_native_tool_names() -> &'static [&'static str] {
+    tool_catalog::DEFAULT_ACTIVE_NATIVE_TOOLS
+}
+
 use self::approval::{ApprovalDecision, ApprovalResult, UserInputDecision};
 #[cfg(test)]
 use self::dispatch::should_parallelize_tool_batch;
@@ -1995,7 +2240,7 @@ use self::dispatch::{
 };
 use self::loop_guard::{AttemptDecision, LoopGuard, OutcomeDecision};
 #[cfg(test)]
-use self::lsp_hooks::{edited_paths_for_tool, parse_patch_paths};
+use self::lsp_hooks::edited_paths_for_tool;
 #[cfg(test)]
 use self::streaming::TOOL_CALL_START_MARKERS;
 use self::streaming::{
@@ -2013,7 +2258,7 @@ use self::tool_catalog::{
 };
 #[cfg(test)]
 use self::tool_catalog::{
-    TOOL_SEARCH_BM25_NAME, maybe_activate_requested_deferred_tool,
+    TOOL_SEARCH_BM25_NAME, TOOL_SEARCH_REGEX_NAME, maybe_activate_requested_deferred_tool,
     preflight_requested_deferred_tool, should_default_defer_tool,
 };
 use self::tool_execution::emit_tool_audit;
diff --git a/crates/tui/src/core/engine/approval.rs b/crates/tui/src/core/engine/approval.rs
index ac04900b..b0f866cc 100644
--- a/crates/tui/src/core/engine/approval.rs
+++ b/crates/tui/src/core/engine/approval.rs
@@ -5,10 +5,14 @@
 //! or whenever a tool requests live user input (`await_user_input`). Channels
 //! and engine state stay private to the parent module.
 
+use std::time::Duration;
+
 use crate::core::events::Event;
 use crate::tools::spec::ToolError;
 use crate::tools::user_input::{UserInputRequest, UserInputResponse};
 
+const USER_INPUT_TIMEOUT: Duration = Duration::from_secs(300);
+
 use super::Engine;
 
 #[derive(Debug, Clone)]
@@ -123,22 +127,43 @@ impl Engine {
                         format!("Request cancelled while awaiting user input{suffix}"),
                     ));
                 }
-                decision = self.rx_user_input.recv() => {
-                    let Some(decision) = decision else {
-                        return Err(ToolError::execution_failed(
-                            "User input channel closed".to_string(),
-                        ));
-                    };
-                    match decision {
-                        UserInputDecision::Submitted { id, response } if id == tool_id => {
-                            return Ok(response);
+                result = tokio::time::timeout(USER_INPUT_TIMEOUT, self.rx_user_input.recv()) => {
+                    match result {
+                        Ok(Some(decision)) => {
+                            match decision {
+                                UserInputDecision::Submitted { id, response } if id == tool_id => {
+                                    return Ok(response);
+                                }
+                                UserInputDecision::Cancelled { id } if id == tool_id => {
+                                    return Err(ToolError::execution_failed(
+                                        "User input cancelled".to_string(),
+                                    ));
+                                }
+                                _ => continue,
+                            }
                         }
-                        UserInputDecision::Cancelled { id } if id == tool_id => {
+                        Ok(None) => {
                             return Err(ToolError::execution_failed(
-                                "User input cancelled".to_string(),
+                                "User input channel closed".to_string(),
+                            ));
+                        }
+                        Err(_) => {
+                            let _ = self
+                                .tx_event
+                                .send(Event::Status {
+                                    message: format!(
+                                        "User input timed out after {}s",
+                                        USER_INPUT_TIMEOUT.as_secs()
+                                    ),
+                                })
+                                .await;
+                            return Err(ToolError::execution_failed(
+                                format!(
+                                    "User input timed out after {}s",
+                                    USER_INPUT_TIMEOUT.as_secs()
+                                ),
                             ));
                         }
-                        _ => continue,
                     }
                 }
             }
diff --git a/crates/tui/src/core/engine/capacity_flow.rs b/crates/tui/src/core/engine/capacity_flow.rs
index cee5fb76..fe357762 100644
--- a/crates/tui/src/core/engine/capacity_flow.rs
+++ b/crates/tui/src/core/engine/capacity_flow.rs
@@ -435,7 +435,7 @@ impl Engine {
         }
 
         if !refreshed {
-            let target_budget = context_input_budget(&self.session.model, TURN_MAX_OUTPUT_TOKENS)
+            let target_budget = context_input_budget(&self.session.model)
                 .unwrap_or(self.config.compaction.token_threshold.max(1));
             if self.estimated_input_tokens() > target_budget {
                 let trimmed = self.trim_oldest_messages_to_budget(target_budget);
diff --git a/crates/tui/src/core/engine/context.rs b/crates/tui/src/core/engine/context.rs
index cb97e774..726f1a92 100644
--- a/crates/tui/src/core/engine/context.rs
+++ b/crates/tui/src/core/engine/context.rs
@@ -28,7 +28,21 @@ const API_MAX_OUTPUT_TOKENS: u32 = 65_536;
 /// model. Uses `API_MAX_OUTPUT_TOKENS` (64K) which fits within common provider
 /// limits (128K+ total). For non-V4 models with smaller context windows, caps
 /// at half the context window.
+///
+/// Override: when the env var `DEEPSEEK_MAX_OUTPUT_TOKENS` is set to a positive
+/// integer, this function returns that value directly. Use this for self-hosted
+/// providers (vLLM/SGLang) whose `max-model-len` is tight and where the
+/// model-table heuristic above would over-allocate. Example: vLLM serving
+/// Qwen3.6 with `--max-model-len 65536` should set
+/// `DEEPSEEK_MAX_OUTPUT_TOKENS=16384` so input + output stays well under the
+/// provider's hard limit.
 pub(super) fn effective_max_output_tokens(model: &str) -> u32 {
+    if let Ok(raw) = std::env::var("DEEPSEEK_MAX_OUTPUT_TOKENS")
+        && let Ok(n) = raw.trim().parse::<u32>()
+        && n > 0
+    {
+        return n;
+    }
     let window = context_window_for_model(model).unwrap_or(128_000);
     if window >= 500_000 {
         // V4-class models on large-context providers: use 64K which is safe
@@ -354,9 +368,35 @@ pub(super) fn estimate_input_tokens_conservative(
         .saturating_add(framing_overhead)
 }
 
-pub(super) fn context_input_budget(model: &str, requested_output_tokens: u32) -> Option<usize> {
-    let window = usize::try_from(context_window_for_model(model)?).ok()?;
-    let output = usize::try_from(requested_output_tokens).ok()?;
+/// Context windows at or above this size reserve the full
+/// [`TURN_MAX_OUTPUT_TOKENS`] (262K) when computing the internal input budget,
+/// leaving room for V4-class interleaved thinking. Below it, the reservation
+/// falls back to [`effective_max_output_tokens`] so a smaller self-hosted
+/// window does not underflow to a negative budget.
+const INTERNAL_BUDGET_LARGE_WINDOW_THRESHOLD: u32 = 500_000;
+
+/// Internal input-side token budget for a model: `window - reserved_output -
+/// headroom`. Used by the preflight check, emergency recovery, and capacity
+/// trimming to decide when to compact.
+///
+/// The reserved-output term is window-dependent:
+///   * `window >= 500K` (V4-class large-context) -> [`TURN_MAX_OUTPUT_TOKENS`]
+///     (262K). Preserves the "leave room for interleaved thinking" contract.
+///   * `window < 500K` (smaller / self-hosted, e.g. a 256K vLLM Qwen window)
+///     -> [`effective_max_output_tokens`], i.e. what the API actually caps
+///     output at. Reserving the full 262K here would compute
+///     `256K - 262K - 1K`, which underflows `checked_sub` to `None` and
+///     *silently disables every preflight and emergency recovery path* — the
+///     session then runs until the provider hard-rejects on context length.
+pub(super) fn context_input_budget(model: &str) -> Option<usize> {
+    let window_tokens = context_window_for_model(model)?;
+    let window = usize::try_from(window_tokens).ok()?;
+    let reserved_output = if window_tokens >= INTERNAL_BUDGET_LARGE_WINDOW_THRESHOLD {
+        TURN_MAX_OUTPUT_TOKENS
+    } else {
+        effective_max_output_tokens(model)
+    };
+    let output = usize::try_from(reserved_output).ok()?;
     window
         .checked_sub(output)
         .and_then(|v| v.checked_sub(CONTEXT_HEADROOM_TOKENS))
diff --git a/crates/tui/src/core/engine/lsp_hooks.rs b/crates/tui/src/core/engine/lsp_hooks.rs
index 1e6da746..544bb903 100644
--- a/crates/tui/src/core/engine/lsp_hooks.rs
+++ b/crates/tui/src/core/engine/lsp_hooks.rs
@@ -7,6 +7,8 @@
 
 use std::path::PathBuf;
 
+use crate::tools::apply_patch::preflight_apply_patch;
+
 use super::*;
 
 /// #136: derive the file path(s) edited by a tool call. Returns the empty
@@ -22,54 +24,19 @@ pub(super) fn edited_paths_for_tool(tool_name: &str, input: &serde_json::Value)
                 Vec::new()
             }
         }
-        "apply_patch" => {
-            // `apply_patch` accepts either a `path` override or a list of
-            // `files` (each `{path, content}`). We try both shapes.
-            let mut out = Vec::new();
-            if let Some(path) = input.get("path").and_then(|v| v.as_str()) {
-                out.push(PathBuf::from(path));
-            }
-            if let Some(files) = input.get("files").and_then(|v| v.as_array()) {
-                for entry in files {
-                    if let Some(path) = entry.get("path").and_then(|v| v.as_str()) {
-                        out.push(PathBuf::from(path));
-                    }
-                }
-            }
-            // Fallback: parse `---`/`+++` headers from a unified diff payload.
-            if out.is_empty()
-                && let Some(patch) = input.get("patch").and_then(|v| v.as_str())
-            {
-                out.extend(parse_patch_paths(patch));
-            }
-            out
-        }
+        "apply_patch" => preflight_apply_patch(input)
+            .map(|preflight| {
+                preflight
+                    .touched_files
+                    .into_iter()
+                    .map(PathBuf::from)
+                    .collect()
+            })
+            .unwrap_or_default(),
         _ => Vec::new(),
     }
 }
 
-/// Lightweight parser for `+++ b/<path>` lines in a unified diff. Used as a
-/// fallback when `apply_patch` is invoked with raw `patch` text and no
-/// `path`/`files` override. We deliberately keep this dumb — the real
-/// `apply_patch` tool already validates the patch shape; we only need a
-/// best-effort hint for the LSP hook.
-pub(super) fn parse_patch_paths(patch: &str) -> Vec<PathBuf> {
-    let mut out = Vec::new();
-    for line in patch.lines() {
-        if let Some(rest) = line.strip_prefix("+++ ") {
-            let trimmed = rest.trim();
-            // Strip leading `b/` per git diff conventions.
-            let path = trimmed.strip_prefix("b/").unwrap_or(trimmed);
-            // Skip `/dev/null` (deletion).
-            if path == "/dev/null" {
-                continue;
-            }
-            out.push(PathBuf::from(path));
-        }
-    }
-    out
-}
-
 impl Engine {
     /// #136: post-edit hook. Inspects the tool name + input, derives the
     /// edited file path, and asks the LSP manager for diagnostics. The
diff --git a/crates/tui/src/core/engine/tests.rs b/crates/tui/src/core/engine/tests.rs
index 851b09ea..f26e0564 100644
--- a/crates/tui/src/core/engine/tests.rs
+++ b/crates/tui/src/core/engine/tests.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+use super::context::TURN_MAX_OUTPUT_TOKENS;
 use crate::models::SystemBlock;
 use crate::test_support::lock_test_env;
 use crate::tools::spec::ToolCapability;
@@ -198,6 +199,37 @@ fn engine_initial_prompt_includes_configured_goal() {
 
     assert!(prompt.contains("<session_goal>"));
     assert!(prompt.contains("Fix goal handoff"));
+    assert!(
+        engine
+            .config
+            .goal_state
+            .lock()
+            .expect("goal lock")
+            .is_active()
+    );
+}
+
+#[test]
+fn refresh_system_prompt_uses_runtime_goal_state() {
+    let (mut engine, _handle) = Engine::new(EngineConfig::default(), &Config::default());
+    {
+        let mut goal = engine.config.goal_state.lock().expect("goal lock");
+        goal.create("Close the runtime goal loop".to_string(), None);
+    }
+
+    engine.refresh_system_prompt(AppMode::Agent);
+    let prompt = match engine.session.system_prompt {
+        Some(SystemPrompt::Text(text)) => text,
+        Some(SystemPrompt::Blocks(blocks)) => blocks
+            .into_iter()
+            .map(|block| block.text)
+            .collect::<Vec<_>>()
+            .join("\n"),
+        None => panic!("expected system prompt"),
+    };
+
+    assert!(prompt.contains("<session_goal>"));
+    assert!(prompt.contains("Close the runtime goal loop"));
 }
 
 #[test]
@@ -385,40 +417,84 @@ fn tool_exec_outcome_tracks_duration() {
 }
 
 #[test]
-fn yolo_mode_keeps_tools_preloaded() {
-    assert!(!should_default_defer_tool("exec_shell", AppMode::Yolo));
+fn core_native_tools_stay_loaded_in_yolo_mode() {
+    let always_load = HashSet::new();
     assert!(!should_default_defer_tool(
-        "mcp_read_resource",
-        AppMode::Yolo
+        "exec_shell",
+        AppMode::Yolo,
+        &always_load
+    ));
+    assert!(should_default_defer_tool(
+        "git_show",
+        AppMode::Yolo,
+        &always_load
     ));
 }
 
 #[test]
 fn non_yolo_mode_retains_default_defer_policy() {
-    // Shell tools are kept loaded in action modes so the model can verify
-    // work without an extra ToolSearch round-trip; non-action tools (e.g.
-    // MCP) still defer.
-    assert!(!should_default_defer_tool("exec_shell", AppMode::Agent));
-    assert!(should_default_defer_tool("exec_shell", AppMode::Plan));
-    assert!(!should_default_defer_tool("read_file", AppMode::Agent));
-    assert!(!should_default_defer_tool("write_file", AppMode::Agent));
+    let always_load = HashSet::new();
+    assert!(!should_default_defer_tool(
+        "exec_shell",
+        AppMode::Agent,
+        &always_load
+    ));
+    assert!(!should_default_defer_tool(
+        "edit_file",
+        AppMode::Agent,
+        &always_load
+    ));
+    assert!(!should_default_defer_tool(
+        "run_tests",
+        AppMode::Agent,
+        &always_load
+    ));
+    assert!(!should_default_defer_tool(
+        "agent_open",
+        AppMode::Agent,
+        &always_load
+    ));
+    assert!(!should_default_defer_tool(
+        "read_file",
+        AppMode::Agent,
+        &always_load
+    ));
+    assert!(!should_default_defer_tool(
+        "write_file",
+        AppMode::Agent,
+        &always_load
+    ));
+    assert!(!should_default_defer_tool(
+        "task_shell_start",
+        AppMode::Agent,
+        &always_load
+    ));
+    assert!(!should_default_defer_tool(
+        "task_shell_wait",
+        AppMode::Agent,
+        &always_load
+    ));
     assert!(should_default_defer_tool(
-        "mcp_read_resource",
-        AppMode::Agent
+        "git_show",
+        AppMode::Agent,
+        &always_load
     ));
 }
 
 #[test]
 fn model_tool_catalog_applies_native_and_mcp_deferral() {
+    let always_load = HashSet::new();
     let catalog = build_model_tool_catalog(
         vec![
             api_tool("read_file"),
             api_tool("write_file"),
             api_tool("exec_shell"),
+            api_tool("edit_file"),
             api_tool("project_map"),
         ],
         vec![api_tool("list_mcp_resources"), api_tool("mcp_server_write")],
         AppMode::Agent,
+        &always_load,
     );
 
     let defer_loading = |name: &str| {
@@ -431,11 +507,152 @@ fn model_tool_catalog_applies_native_and_mcp_deferral() {
     assert_eq!(defer_loading("read_file"), Some(false));
     assert_eq!(defer_loading("write_file"), Some(false));
     assert_eq!(defer_loading("exec_shell"), Some(false));
+    assert_eq!(defer_loading("edit_file"), Some(false));
     assert_eq!(defer_loading("project_map"), Some(true));
     assert_eq!(defer_loading("list_mcp_resources"), Some(false));
     assert_eq!(defer_loading("mcp_server_write"), Some(true));
 }
 
+#[test]
+fn agent_catalog_keeps_edit_file_loaded_when_fuzz_is_omitted() {
+    let (engine, _handle) = Engine::new(EngineConfig::default(), &Config::default());
+    let registry = engine
+        .build_turn_tool_registry_builder(
+            AppMode::Agent,
+            engine.config.todos.clone(),
+            engine.config.plan_state.clone(),
+        )
+        .build(engine.build_tool_context(AppMode::Agent, false));
+    let always_load = HashSet::new();
+    let catalog = build_model_tool_catalog(
+        registry.to_api_tools_with_cache(true),
+        vec![],
+        AppMode::Agent,
+        &always_load,
+    );
+    let edit = catalog
+        .iter()
+        .find(|tool| tool.name == "edit_file")
+        .expect("edit_file registered");
+
+    assert_eq!(edit.defer_loading, Some(false));
+    let required = edit.input_schema["required"]
+        .as_array()
+        .expect("edit_file schema should include required fields");
+    assert!(required.iter().any(|field| field.as_str() == Some("path")));
+    assert!(
+        required
+            .iter()
+            .any(|field| field.as_str() == Some("search"))
+    );
+    assert!(
+        required
+            .iter()
+            .any(|field| field.as_str() == Some("replace"))
+    );
+    assert!(!required.iter().any(|field| field.as_str() == Some("fuzz")));
+    assert_eq!(
+        edit.input_schema["properties"]["fuzz"]["type"].as_str(),
+        Some("boolean")
+    );
+
+    let active_at_batch_start = initial_active_tools(&catalog);
+    assert!(active_at_batch_start.contains("edit_file"));
+    let mut hydrated_this_batch = HashSet::new();
+    assert!(
+        maybe_hydrate_requested_deferred_tool(
+            "edit_file",
+            &json!({
+                "path": "src/foo.rs",
+                "search": "before",
+                "replace": "after"
+            }),
+            &catalog,
+            &active_at_batch_start,
+            &mut hydrated_this_batch,
+        )
+        .is_none(),
+        "loaded edit_file calls without fuzz should execute instead of hydrating the schema"
+    );
+    assert!(hydrated_this_batch.is_empty());
+}
+
+#[test]
+fn tools_always_load_overrides_default_native_deferral() {
+    let always_load = HashSet::from(["git_show".to_string()]);
+    assert!(!should_default_defer_tool(
+        "git_show",
+        AppMode::Agent,
+        &always_load
+    ));
+}
+
+#[test]
+#[ignore = "one-shot metric for scripts/measure-tool-catalog.py"]
+#[allow(clippy::print_stderr)]
+fn print_agent_tool_catalog_metrics() {
+    let tmp = tempdir().expect("tempdir");
+    let context = crate::tools::ToolContext::new(tmp.path().to_path_buf());
+    let client = DeepSeekClient::new(&Config {
+        api_key: Some("test-key".to_string()),
+        ..Config::default()
+    })
+    .expect("stub client");
+    let manager = crate::tools::subagent::new_shared_subagent_manager(tmp.path().to_path_buf(), 8);
+    let runtime = crate::tools::subagent::SubAgentRuntime::new(
+        client,
+        DEFAULT_TEXT_MODEL.to_string(),
+        context.clone(),
+        true,
+        None,
+        manager.clone(),
+    );
+    let registry = crate::tools::ToolRegistryBuilder::new()
+        .with_agent_tools(true)
+        .with_todo_tool(new_shared_todo_list())
+        .with_plan_tool(new_shared_plan_state())
+        .with_review_tool(None, DEFAULT_TEXT_MODEL.to_string())
+        .with_rlm_tool(None, DEFAULT_TEXT_MODEL.to_string())
+        .with_recall_archive_tool()
+        .with_notify_tool()
+        .with_subagent_tools(manager, runtime)
+        .build(context);
+    let baseline_catalog = registry.to_api_tools_with_cache(true);
+    let baseline_json = serde_json::to_vec(&baseline_catalog).expect("serialize baseline");
+
+    let always_load = HashSet::new();
+    let mut catalog = build_model_tool_catalog(
+        baseline_catalog.clone(),
+        vec![],
+        AppMode::Agent,
+        &always_load,
+    );
+    ensure_advanced_tooling(&mut catalog, AppMode::Agent, &always_load);
+    let active = initial_active_tools(&catalog);
+    let active_catalog = active_tools_for_step(&catalog, &active, false);
+    let active_json = serde_json::to_vec(&active_catalog).expect("serialize active");
+    let reduction_percent = if baseline_json.is_empty() {
+        0.0
+    } else {
+        100.0 * (baseline_json.len().saturating_sub(active_json.len())) as f64
+            / baseline_json.len() as f64
+    };
+
+    eprintln!(
+        "TOOL_CATALOG_METRICS {}",
+        serde_json::json!({
+            "baseline_tools": baseline_catalog.len(),
+            "baseline_bytes": baseline_json.len(),
+            "baseline_tokens_est": baseline_json.len().div_ceil(4),
+            "active_tools": active_catalog.len(),
+            "active_bytes": active_json.len(),
+            "active_tokens_est": active_json.len().div_ceil(4),
+            "reduction_percent": reduction_percent,
+            "active_tool_names": active_catalog.iter().map(|tool| tool.name.as_str()).collect::<Vec<_>>(),
+        })
+    );
+}
+
 #[test]
 fn deferred_edit_file_first_use_hydrates_schema_without_execution() {
     let mut edit = api_tool("edit_file");
@@ -510,14 +727,25 @@ fn deferred_edit_file_first_use_hydrates_schema_without_execution() {
 }
 
 #[test]
-fn model_tool_catalog_keeps_everything_loaded_in_yolo_mode() {
+fn model_tool_catalog_defers_non_core_native_tools_in_yolo_mode() {
+    let always_load = HashSet::new();
     let catalog = build_model_tool_catalog(
-        vec![api_tool("project_map")],
+        vec![api_tool("read_file"), api_tool("project_map")],
         vec![api_tool("mcp_server_write")],
         AppMode::Yolo,
+        &always_load,
     );
 
-    assert!(catalog.iter().all(|tool| tool.defer_loading == Some(false)));
+    let defer_loading = |name: &str| {
+        catalog
+            .iter()
+            .find(|tool| tool.name == name)
+            .and_then(|tool| tool.defer_loading)
+    };
+
+    assert_eq!(defer_loading("read_file"), Some(false));
+    assert_eq!(defer_loading("project_map"), Some(true));
+    assert_eq!(defer_loading("mcp_server_write"), Some(false));
 }
 
 #[test]
@@ -525,6 +753,7 @@ fn model_tool_catalog_sorts_each_partition_for_prefix_cache_stability() {
     // Regression for #263: deterministic byte order of the tools array is a
     // hard requirement for DeepSeek's KV prefix cache. Built-ins stay as a
     // contiguous prefix; MCP tools follow. Within each partition: alphabetical.
+    let always_load = HashSet::new();
     let catalog = build_model_tool_catalog(
         vec![
             api_tool("read_file"),
@@ -533,6 +762,7 @@ fn model_tool_catalog_sorts_each_partition_for_prefix_cache_stability() {
         ],
         vec![api_tool("mcp_zoo_b"), api_tool("mcp_aardvark_a")],
         AppMode::Yolo,
+        &always_load,
     );
 
     let names: Vec<&str> = catalog.iter().map(|t| t.name.as_str()).collect();
@@ -587,11 +817,18 @@ fn deferred_tool_preflight_loads_edit_schema_without_executing_bad_aliases() {
             engine.config.plan_state.clone(),
         )
         .build(engine.build_tool_context(AppMode::Agent, false));
-    let catalog = build_model_tool_catalog(
+    let always_load = HashSet::new();
+    let mut catalog = build_model_tool_catalog(
         registry.to_api_tools_with_cache(true),
         vec![],
         AppMode::Agent,
+        &always_load,
     );
+    catalog
+        .iter_mut()
+        .find(|tool| tool.name == "edit_file")
+        .expect("edit_file registered")
+        .defer_loading = Some(true);
     let mut active = initial_active_tools(&catalog);
     assert!(!active.contains("edit_file"));
 
@@ -632,10 +869,12 @@ fn deferred_tool_preflight_guides_checklist_update_list_replacement() {
             engine.config.plan_state.clone(),
         )
         .build(engine.build_tool_context(AppMode::Agent, false));
+    let always_load = HashSet::new();
     let catalog = build_model_tool_catalog(
         registry.to_api_tools_with_cache(true),
         vec![],
         AppMode::Agent,
+        &always_load,
     );
     let mut active = initial_active_tools(&catalog);
     assert!(!active.contains("checklist_update"));
@@ -706,6 +945,9 @@ fn turn_tool_registry_builder_keeps_plan_mode_read_only_for_files() {
     assert!(!registry.contains("rlm"));
     assert!(!registry.contains("fim_edit"));
     assert!(registry.contains("update_plan"));
+    assert!(registry.contains("create_goal"));
+    assert!(registry.contains("get_goal"));
+    assert!(registry.contains("update_goal"));
     assert!(registry.contains("task_list"));
     assert!(registry.contains("task_read"));
     assert!(registry.contains("handle_read"));
@@ -758,6 +1000,28 @@ fn parent_turn_registry_includes_recall_archive_for_investigative_modes() {
     }
 }
 
+#[test]
+fn parent_turn_registry_includes_goal_tools_for_all_modes() {
+    let (engine, _handle) = Engine::new(EngineConfig::default(), &Config::default());
+
+    for mode in [AppMode::Plan, AppMode::Agent, AppMode::Yolo] {
+        let registry = engine
+            .build_turn_tool_registry_builder(
+                mode,
+                engine.config.todos.clone(),
+                engine.config.plan_state.clone(),
+            )
+            .build(engine.build_tool_context(mode, false));
+
+        for name in ["create_goal", "get_goal", "update_goal"] {
+            assert!(
+                registry.contains(name),
+                "parent {mode:?} registry should expose {name}"
+            );
+        }
+    }
+}
+
 #[test]
 fn agent_mode_can_build_auto_approved_tool_context() {
     let (engine, _handle) = Engine::new(EngineConfig::default(), &Config::default());
@@ -914,9 +1178,12 @@ fn detects_context_length_errors_from_provider_payloads() {
 
 #[test]
 fn context_budget_reserves_output_and_headroom() {
+    // Serialize with other tests that mutate DEEPSEEK_MAX_OUTPUT_TOKENS so
+    // the internal effective_max_output_tokens() call sees a stable env.
+    let _lock = lock_test_env();
     // V4 has a 1M context window — the only family that comfortably hosts
     // a 256K output reservation without saturating the input budget to 0.
-    let budget = context_input_budget("deepseek-v4-pro", TURN_MAX_OUTPUT_TOKENS)
+    let budget = context_input_budget("deepseek-v4-pro")
         .expect("deepseek-v4-pro should have a known context window");
     let v4_window: usize = 1_000_000;
     let expected = v4_window - (TURN_MAX_OUTPUT_TOKENS as usize) - 1_024usize;
@@ -925,6 +1192,9 @@ fn context_budget_reserves_output_and_headroom() {
 
 #[test]
 fn effective_max_output_tokens_caps_api_request_for_large_window_models() {
+    // Serialize with other tests that mutate DEEPSEEK_MAX_OUTPUT_TOKENS so
+    // v4_cap and flash_cap below see the same env state.
+    let _lock = lock_test_env();
     // V4 models have a 1M context window but the API request cap must stay
     // well below common provider limits (e.g., 131K total on self-hosted
     // vLLM/SGLang). The cap should never exceed 65K.
@@ -942,32 +1212,101 @@ fn effective_max_output_tokens_caps_api_request_for_large_window_models() {
     assert_eq!(v4_cap, flash_cap);
 }
 
+struct ScopedDeepSeekMaxOutputTokens {
+    previous: Option<OsString>,
+}
+
+impl ScopedDeepSeekMaxOutputTokens {
+    fn set(value: &str) -> Self {
+        let previous = std::env::var_os("DEEPSEEK_MAX_OUTPUT_TOKENS");
+        // Safety: tests using this helper serialize with lock_test_env() and
+        // restore the original value in Drop.
+        unsafe {
+            std::env::set_var("DEEPSEEK_MAX_OUTPUT_TOKENS", value);
+        }
+        Self { previous }
+    }
+
+    fn unset() -> Self {
+        let previous = std::env::var_os("DEEPSEEK_MAX_OUTPUT_TOKENS");
+        // Safety: see set().
+        unsafe {
+            std::env::remove_var("DEEPSEEK_MAX_OUTPUT_TOKENS");
+        }
+        Self { previous }
+    }
+}
+
+impl Drop for ScopedDeepSeekMaxOutputTokens {
+    fn drop(&mut self) {
+        // Safety: tests using this helper serialize with lock_test_env().
+        unsafe {
+            if let Some(previous) = self.previous.take() {
+                std::env::set_var("DEEPSEEK_MAX_OUTPUT_TOKENS", previous);
+            } else {
+                std::env::remove_var("DEEPSEEK_MAX_OUTPUT_TOKENS");
+            }
+        }
+    }
+}
+
 #[test]
-fn internal_context_budget_unaffected_by_api_request_cap() {
-    // The internal context budget (used for compaction/preflight/recovery)
-    // must still use the full TURN_MAX_OUTPUT_TOKENS headroom, NOT the
-    // smaller API request cap. This ensures long-context V4 sessions don't
-    // compact prematurely.
-    let internal_budget = context_input_budget("deepseek-v4-pro", TURN_MAX_OUTPUT_TOKENS)
-        .expect("V4 should have a known context window");
-    let api_cap_budget = context_input_budget(
-        "deepseek-v4-pro",
-        effective_max_output_tokens("deepseek-v4-pro"),
-    )
-    .expect("V4 should have a known context window");
+fn effective_max_output_tokens_env_override_returns_positive_value() {
+    let _lock = lock_test_env();
+    let _guard = ScopedDeepSeekMaxOutputTokens::set("16384");
 
-    // Internal budget reserves 262K for output; API-cap budget would only
-    // reserve 64K. Internal budget must be smaller (more conservative).
-    assert!(
-        internal_budget < api_cap_budget,
-        "Internal budget ({internal_budget}) should be smaller than API-cap budget ({api_cap_budget}) \
-         because it reserves more headroom for output"
-    );
+    // Override applies regardless of model — V4 hosted, V4 flash, sub-500K
+    // self-hosted all return the env value verbatim.
+    assert_eq!(effective_max_output_tokens("deepseek-v4-pro"), 16_384);
+    assert_eq!(effective_max_output_tokens("deepseek-v4-flash"), 16_384);
+    assert_eq!(effective_max_output_tokens("qwen3-32b-256k"), 16_384);
+}
 
-    // Verify the internal budget is what the compaction logic actually uses.
+#[test]
+fn effective_max_output_tokens_env_override_rejects_zero_and_invalid() {
+    let _lock = lock_test_env();
+    // Establish the heuristic baseline with the env unset.
+    let baseline = {
+        let _guard = ScopedDeepSeekMaxOutputTokens::unset();
+        effective_max_output_tokens("deepseek-v4-pro")
+    };
+    assert!(baseline > 0);
+
+    // 0, non-numeric, and empty values must all fall through to the heuristic
+    // rather than producing a zero/garbage cap that would silently break
+    // request budgeting.
+    for raw in ["0", "abc", "", "  ", "-1"] {
+        let _guard = ScopedDeepSeekMaxOutputTokens::set(raw);
+        assert_eq!(
+            effective_max_output_tokens("deepseek-v4-pro"),
+            baseline,
+            "env={raw:?} should fall through to heuristic"
+        );
+    }
+}
+
+#[test]
+fn internal_context_budget_tiers_reserved_output_by_window() {
+    // Serialize with other tests that mutate DEEPSEEK_MAX_OUTPUT_TOKENS so
+    // both branches below see a stable env.
+    let _lock = lock_test_env();
+    // Large-context (>=500K) models reserve the full TURN_MAX_OUTPUT_TOKENS
+    // headroom so long V4 sessions don't compact prematurely.
+    let internal_budget =
+        context_input_budget("deepseek-v4-pro").expect("V4 should have a known context window");
     let v4_window: usize = 1_000_000;
     let expected_internal = v4_window - (TURN_MAX_OUTPUT_TOKENS as usize) - 1_024usize;
     assert_eq!(internal_budget, expected_internal);
+
+    // Sub-500K windows cross into the effective-cap branch: a 256K self-hosted
+    // deployment must yield a usable positive budget rather than None. The
+    // previous formula reserved the full 262K and computed 256K - 262K - 1K,
+    // which underflowed to None and silently disabled preflight/recovery.
+    let small_window_budget = context_input_budget("qwen3-32b-256k")
+        .expect("a 256K-suffix model must yield Some budget via the effective-cap branch");
+    let effective_output = effective_max_output_tokens("qwen3-32b-256k") as usize;
+    let expected_small = 256_000 - effective_output - 1_024;
+    assert_eq!(small_window_budget, expected_small);
 }
 
 #[test]
@@ -1300,6 +1639,28 @@ fn refresh_system_prompt_is_noop_when_unchanged() {
     assert_eq!(engine.session.system_prompt, first_prompt);
 }
 
+#[test]
+fn engine_prompt_respects_hidden_thinking_config() {
+    let tmp = tempdir().expect("tempdir");
+    let config = EngineConfig {
+        workspace: tmp.path().to_path_buf(),
+        locale_tag: "zh-Hans".to_string(),
+        show_thinking: false,
+        ..Default::default()
+    };
+    let (engine, _handle) = Engine::new(config, &Config::default());
+    let prompt = match engine.session.system_prompt.as_ref() {
+        Some(SystemPrompt::Text(text)) => text,
+        Some(SystemPrompt::Blocks(_)) => panic!("expected text system prompt"),
+        None => panic!("expected system prompt"),
+    };
+
+    assert!(prompt.contains("## Hidden Thinking Language"));
+    assert!(prompt.contains("reasoning_content"));
+    assert!(prompt.contains("English"));
+    assert!(!prompt.contains("## 语言再次提醒"));
+}
+
 fn sync_runtime_system_prompt_override(engine: &mut Engine, system_prompt: SystemPrompt) {
     engine.session.compaction_summary_prompt =
         extract_compaction_summary_prompt(Some(system_prompt.clone()));
@@ -1732,7 +2093,8 @@ fn tool_search_activates_discovered_deferred_tools() {
             cache_control: None,
         },
     ];
-    ensure_advanced_tooling(&mut catalog, AppMode::Agent);
+    let always_load = HashSet::new();
+    ensure_advanced_tooling(&mut catalog, AppMode::Agent, &always_load);
     let mut active = initial_active_tools(&catalog);
     let result = execute_tool_search(
         TOOL_SEARCH_BM25_NAME,
@@ -1745,6 +2107,96 @@ fn tool_search_activates_discovered_deferred_tools() {
     assert!(active.contains("read_file"));
 }
 
+fn tool_search_catalog_with_matches(count: usize) -> Vec<Tool> {
+    let mut catalog = (0..count)
+        .map(|idx| Tool {
+            tool_type: None,
+            name: format!("matching_tool_{idx:03}"),
+            description: "Matching deferred test tool".to_string(),
+            input_schema: json!({"type":"object","properties":{"query":{"type":"string"}}}),
+            allowed_callers: Some(vec!["direct".to_string()]),
+            defer_loading: Some(true),
+            input_examples: None,
+            strict: None,
+            cache_control: None,
+        })
+        .collect::<Vec<_>>();
+    let always_load = HashSet::new();
+    ensure_advanced_tooling(&mut catalog, AppMode::Agent, &always_load);
+    catalog
+}
+
+fn tool_search_reference_count(result: &ToolResult) -> usize {
+    result
+        .metadata
+        .as_ref()
+        .and_then(|metadata| metadata.get("tool_references"))
+        .and_then(|references| references.as_array())
+        .map_or(0, Vec::len)
+}
+
+#[test]
+fn tool_search_defaults_to_twenty_results_for_regex_and_bm25() {
+    let catalog = tool_search_catalog_with_matches(25);
+
+    for tool_name in [TOOL_SEARCH_REGEX_NAME, TOOL_SEARCH_BM25_NAME] {
+        let mut active = initial_active_tools(&catalog);
+        let result = execute_tool_search(
+            tool_name,
+            &json!({"query":"matching"}),
+            &catalog,
+            &mut active,
+        )
+        .expect("search succeeds");
+
+        assert_eq!(tool_search_reference_count(&result), 20);
+    }
+}
+
+#[test]
+fn tool_search_respects_and_caps_max_results() {
+    let catalog = tool_search_catalog_with_matches(120);
+
+    let mut active = initial_active_tools(&catalog);
+    let limited = execute_tool_search(
+        TOOL_SEARCH_BM25_NAME,
+        &json!({"query":"matching","max_results":7}),
+        &catalog,
+        &mut active,
+    )
+    .expect("search succeeds");
+    assert_eq!(tool_search_reference_count(&limited), 7);
+
+    let mut active = initial_active_tools(&catalog);
+    let capped = execute_tool_search(
+        TOOL_SEARCH_REGEX_NAME,
+        &json!({"query":"matching","max_results":999}),
+        &catalog,
+        &mut active,
+    )
+    .expect("search succeeds");
+    assert_eq!(tool_search_reference_count(&capped), 100);
+}
+
+#[test]
+fn tool_search_schema_exposes_max_results_default_and_cap() {
+    let mut catalog = Vec::new();
+    let always_load = HashSet::new();
+    ensure_advanced_tooling(&mut catalog, AppMode::Agent, &always_load);
+
+    for tool_name in [TOOL_SEARCH_REGEX_NAME, TOOL_SEARCH_BM25_NAME] {
+        let tool = catalog
+            .iter()
+            .find(|tool| tool.name == tool_name)
+            .expect("tool search definition exists");
+        let schema = &tool.input_schema["properties"]["max_results"];
+
+        assert_eq!(schema["default"], 20);
+        assert_eq!(schema["maximum"], 100);
+        assert_eq!(schema["minimum"], 1);
+    }
+}
+
 #[tokio::test]
 async fn code_execution_runs_python_and_returns_result_payload() {
     let tmp = tempdir().expect("tempdir");
@@ -1759,7 +2211,8 @@ async fn code_execution_runs_python_and_returns_result_payload() {
 #[test]
 fn plan_mode_catalog_skips_code_execution_tool_but_agent_keeps_it() {
     let mut plan_catalog = vec![api_tool("read_file")];
-    ensure_advanced_tooling(&mut plan_catalog, AppMode::Plan);
+    let always_load = HashSet::new();
+    ensure_advanced_tooling(&mut plan_catalog, AppMode::Plan, &always_load);
     assert!(
         !plan_catalog
             .iter()
@@ -1768,7 +2221,7 @@ fn plan_mode_catalog_skips_code_execution_tool_but_agent_keeps_it() {
     );
 
     let mut agent_catalog = vec![api_tool("read_file")];
-    ensure_advanced_tooling(&mut agent_catalog, AppMode::Agent);
+    ensure_advanced_tooling(&mut agent_catalog, AppMode::Agent, &always_load);
     assert!(
         agent_catalog
             .iter()
@@ -2233,9 +2686,9 @@ fn edited_paths_for_write_file_returns_path() {
 }
 
 #[test]
-fn edited_paths_for_apply_patch_with_files_returns_each_path() {
+fn edited_paths_for_apply_patch_with_changes_returns_each_path() {
     let input = json!({
-        "files": [
+        "changes": [
             { "path": "a.rs", "content": "" },
             { "path": "b.rs", "content": "" }
         ]
@@ -2253,6 +2706,15 @@ fn edited_paths_for_apply_patch_with_diff_text_extracts_paths() {
     assert_eq!(paths, vec![PathBuf::from("foo.rs")]);
 }
 
+#[test]
+fn edited_paths_for_apply_patch_with_invalid_diff_returns_empty() {
+    let input = json!({
+        "patch": "@@ -1 +1 @@\n-old\n+new\n"
+    });
+    let paths = edited_paths_for_tool("apply_patch", &input);
+    assert!(paths.is_empty());
+}
+
 #[test]
 fn edited_paths_for_unknown_tool_returns_empty() {
     let input = json!({ "path": "irrelevant.rs" });
@@ -2264,8 +2726,8 @@ fn edited_paths_for_unknown_tool_returns_empty() {
 
 #[test]
 fn parse_patch_paths_skips_dev_null() {
-    let patch = "--- a/keep.rs\n+++ b/keep.rs\n--- a/deleted.rs\n+++ /dev/null\n";
-    let paths = parse_patch_paths(patch);
+    let patch = "--- a/keep.rs\n+++ b/keep.rs\n@@ -1 +1 @@\n-old\n+new\n--- a/deleted.rs\n+++ /dev/null\n@@ -1 +0,0 @@\n-delete me\n";
+    let paths = edited_paths_for_tool("apply_patch", &json!({ "patch": patch }));
     assert_eq!(paths, vec![PathBuf::from("keep.rs")]);
 }
 
diff --git a/crates/tui/src/core/engine/tool_catalog.rs b/crates/tui/src/core/engine/tool_catalog.rs
index 3ce7cdac..60b6166b 100644
--- a/crates/tui/src/core/engine/tool_catalog.rs
+++ b/crates/tui/src/core/engine/tool_catalog.rs
@@ -12,7 +12,7 @@ use std::time::Duration;
 use serde_json::{Value, json};
 
 use crate::models::Tool;
-use crate::tools::spec::{ToolError, ToolResult, required_str};
+use crate::tools::spec::{ToolError, ToolResult, optional_u64, required_str};
 use crate::tui::app::AppMode;
 
 pub(super) const MULTI_TOOL_PARALLEL_NAME: &str = "multi_tool_use.parallel";
@@ -20,72 +20,70 @@ pub(super) const REQUEST_USER_INPUT_NAME: &str = "request_user_input";
 pub(super) const CODE_EXECUTION_TOOL_NAME: &str = "code_execution";
 const CODE_EXECUTION_TOOL_TYPE: &str = "code_execution_20250825";
 pub(super) use crate::tools::js_execution::JS_EXECUTION_TOOL_NAME;
-const TOOL_SEARCH_REGEX_NAME: &str = "tool_search_tool_regex";
+pub(super) const TOOL_SEARCH_REGEX_NAME: &str = "tool_search_tool_regex";
 const TOOL_SEARCH_REGEX_TYPE: &str = "tool_search_tool_regex_20251119";
 pub(super) const TOOL_SEARCH_BM25_NAME: &str = "tool_search_tool_bm25";
 const TOOL_SEARCH_BM25_TYPE: &str = "tool_search_tool_bm25_20251119";
+const TOOL_SEARCH_DEFAULT_MAX_RESULTS: usize = 20;
+const TOOL_SEARCH_MAX_RESULTS_LIMIT: usize = 100;
 
 pub(super) fn is_tool_search_tool(name: &str) -> bool {
     matches!(name, TOOL_SEARCH_REGEX_NAME | TOOL_SEARCH_BM25_NAME)
 }
 
-pub(super) fn should_default_defer_tool(name: &str, mode: AppMode) -> bool {
-    if mode == AppMode::Yolo {
+pub(super) const DEFAULT_ACTIVE_NATIVE_TOOLS: &[&str] = &[
+    "agent_open",
+    "apply_patch",
+    "checklist_write",
+    "edit_file",
+    "exec_interact",
+    "exec_shell",
+    "exec_shell_interact",
+    "exec_shell_wait",
+    "exec_wait",
+    "fetch_url",
+    "file_search",
+    "git_diff",
+    "git_status",
+    "grep_files",
+    "list_dir",
+    "read_file",
+    "run_tests",
+    "task_create",
+    "task_list",
+    "task_read",
+    "task_shell_start",
+    "task_shell_wait",
+    "update_plan",
+    "web_search",
+    "write_file",
+];
+
+pub(super) fn should_default_defer_tool(
+    name: &str,
+    _mode: AppMode,
+    always_load: &HashSet<String>,
+) -> bool {
+    if always_load.contains(name) {
         return false;
     }
 
-    // Shell exec tools are kept active in Agent so the model can run
-    // verification commands (build/test/git/cargo) without first having to
-    // discover them through ToolSearch. Plan mode does not register shell
-    // execution tools.
-    let always_loaded_in_action_modes = matches!(mode, AppMode::Agent)
-        && matches!(
-            name,
-            "exec_shell"
-                | "exec_shell_wait"
-                | "exec_shell_interact"
-                | "exec_wait"
-                | "exec_interact"
-        );
-    if always_loaded_in_action_modes {
+    if is_tool_search_tool(name) {
         return false;
     }
 
-    !matches!(
-        name,
-        "read_file"
-            | "write_file"
-            | "list_dir"
-            | "grep_files"
-            | "file_search"
-            | "diagnostics"
-            | "rlm_open"
-            | "rlm_eval"
-            | "rlm_configure"
-            | "rlm_close"
-            | "rlm_session_objects"
-            | "handle_read"
-            | "recall_archive"
-            | "notify"
-            | MULTI_TOOL_PARALLEL_NAME
-            | "update_plan"
-            | "checklist_write"
-            | "todo_write"
-            | "task_create"
-            | "task_list"
-            | "task_read"
-            | "task_gate_run"
-            | "task_shell_start"
-            | "task_shell_wait"
-            | "github_issue_context"
-            | "github_pr_context"
-            | REQUEST_USER_INPUT_NAME
-    )
+    !DEFAULT_ACTIVE_NATIVE_TOOLS
+        .iter()
+        .any(|core_tool| core_tool == &name)
 }
 
-pub(super) fn apply_native_tool_deferral(catalog: &mut [Tool], mode: AppMode) {
+pub(super) fn apply_native_tool_deferral(
+    catalog: &mut [Tool],
+    mode: AppMode,
+    always_load: &HashSet<String>,
+) {
     for tool in catalog {
-        tool.defer_loading = Some(should_default_defer_tool(&tool.name, mode));
+        tool.defer_loading = Some(should_default_defer_tool(&tool.name, mode, always_load));
     }
 }
 
@@ -111,8 +109,9 @@ pub(super) fn build_model_tool_catalog(
     mut native_tools: Vec<Tool>,
     mut mcp_tools: Vec<Tool>,
     mode: AppMode,
+    always_load: &HashSet<String>,
 ) -> Vec<Tool> {
-    apply_native_tool_deferral(&mut native_tools, mode);
+    apply_native_tool_deferral(&mut native_tools, mode, always_load);
     apply_mcp_tool_deferral(&mut mcp_tools, mode);
     // Sort each partition by name for prefix-cache stability (#263). The
     // upstream `to_api_tools()` already sorts the registry's HashMap output;
@@ -126,7 +125,11 @@ pub(super) fn build_model_tool_catalog(
     native_tools
 }
 
-pub(super) fn ensure_advanced_tooling(catalog: &mut Vec<Tool>, mode: AppMode) {
+pub(super) fn ensure_advanced_tooling(
+    catalog: &mut Vec<Tool>,
+    mode: AppMode,
+    always_load: &HashSet<String>,
+) {
     // code_execution depends on a locally-installed Python interpreter
     // (python3 / python / py -3). Before v0.8.31, the tool was always
     // advertised and would fail at execution time on Windows where
@@ -150,7 +153,11 @@ pub(super) fn ensure_advanced_tooling(catalog: &mut Vec<Tool>, mode: AppMode) {
                 "required": ["code"]
             }),
             allowed_callers: Some(vec!["direct".to_string()]),
-            defer_loading: Some(false),
+            defer_loading: Some(should_default_defer_tool(
+                CODE_EXECUTION_TOOL_NAME,
+                mode,
+                always_load,
+            )),
             input_examples: None,
             strict: None,
             cache_control: None,
@@ -166,7 +173,9 @@ pub(super) fn ensure_advanced_tooling(catalog: &mut Vec<Tool>, mode: AppMode) {
         && !catalog.iter().any(|t| t.name == JS_EXECUTION_TOOL_NAME)
         && crate::dependencies::resolve_node().is_some()
     {
-        catalog.push(crate::tools::js_execution::js_execution_tool_definition());
+        let mut tool = crate::tools::js_execution::js_execution_tool_definition();
+        tool.defer_loading = Some(should_default_defer_tool(&tool.name, mode, always_load));
+        catalog.push(tool);
     }
 
     if !catalog.iter().any(|t| t.name == TOOL_SEARCH_REGEX_NAME) {
@@ -177,7 +186,14 @@ pub(super) fn ensure_advanced_tooling(catalog: &mut Vec<Tool>, mode: AppMode) {
             input_schema: json!({
                 "type": "object",
                 "properties": {
-                    "query": { "type": "string", "description": "Regex pattern to search tool names/descriptions/schema." }
+                    "query": { "type": "string", "description": "Regex pattern to search tool names/descriptions/schema." },
+                    "max_results": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": TOOL_SEARCH_MAX_RESULTS_LIMIT,
+                        "default": TOOL_SEARCH_DEFAULT_MAX_RESULTS,
+                        "description": "Maximum number of matching tool references to return."
+                    }
                 },
                 "required": ["query"]
             }),
@@ -197,7 +213,14 @@ pub(super) fn ensure_advanced_tooling(catalog: &mut Vec<Tool>, mode: AppMode) {
             input_schema: json!({
                 "type": "object",
                 "properties": {
-                    "query": { "type": "string", "description": "Natural language query for tool discovery." }
+                    "query": { "type": "string", "description": "Natural language query for tool discovery." },
+                    "max_results": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": TOOL_SEARCH_MAX_RESULTS_LIMIT,
+                        "default": TOOL_SEARCH_DEFAULT_MAX_RESULTS,
+                        "description": "Maximum number of matching tool references to return."
+                    }
                 },
                 "required": ["query"]
             }),
@@ -279,7 +302,11 @@ fn tool_search_haystack(tool: &Tool) -> String {
     )
 }
 
-fn discover_tools_with_regex(catalog: &[Tool], query: &str) -> Result<Vec<String>, ToolError> {
+fn discover_tools_with_regex(
+    catalog: &[Tool],
+    query: &str,
+    max_results: usize,
+) -> Result<Vec<String>, ToolError> {
     let regex = regex::Regex::new(query)
         .map_err(|err| ToolError::invalid_input(format!("Invalid regex query: {err}")))?;
 
@@ -292,14 +319,14 @@ fn discover_tools_with_regex(catalog: &[Tool], query: &str) -> Result<Vec<String
         if regex.is_match(&hay) {
             matches.push(tool.name.clone());
         }
-        if matches.len() >= 5 {
+        if matches.len() >= max_results {
             break;
         }
     }
     Ok(matches)
 }
 
-fn discover_tools_with_bm25_like(catalog: &[Tool], query: &str) -> Vec<String> {
+fn discover_tools_with_bm25_like(catalog: &[Tool], query: &str, max_results: usize) -> Vec<String> {
     let terms: Vec<String> = query
         .split_whitespace()
         .map(|term| term.trim().to_lowercase())
@@ -329,7 +356,11 @@ fn discover_tools_with_bm25_like(catalog: &[Tool], query: &str) -> Vec<String> {
         }
     }
     scored.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.cmp(&b.1)));
-    scored.into_iter().take(5).map(|(_, name)| name).collect()
+    scored
+        .into_iter()
+        .take(max_results)
+        .map(|(_, name)| name)
+        .collect()
 }
 
 fn edit_distance(a: &str, b: &str) -> usize {
@@ -644,10 +675,17 @@ pub(super) fn execute_tool_search(
     active_tools: &mut HashSet<String>,
 ) -> Result<ToolResult, ToolError> {
     let query = required_str(input, "query")?;
+    let max_results = usize::try_from(optional_u64(
+        input,
+        "max_results",
+        TOOL_SEARCH_DEFAULT_MAX_RESULTS as u64,
+    ))
+    .unwrap_or(TOOL_SEARCH_DEFAULT_MAX_RESULTS)
+    .clamp(1, TOOL_SEARCH_MAX_RESULTS_LIMIT);
     let discovered = if tool_name == TOOL_SEARCH_REGEX_NAME {
-        discover_tools_with_regex(catalog, query)?
+        discover_tools_with_regex(catalog, query, max_results)?
     } else {
-        discover_tools_with_bm25_like(catalog, query)
+        discover_tools_with_bm25_like(catalog, query, max_results)
     };
 
     for name in &discovered {
diff --git a/crates/tui/src/core/engine/tool_setup.rs b/crates/tui/src/core/engine/tool_setup.rs
index 2354d6a8..b31e9ce0 100644
--- a/crates/tui/src/core/engine/tool_setup.rs
+++ b/crates/tui/src/core/engine/tool_setup.rs
@@ -52,11 +52,13 @@ impl Engine {
                 .with_runtime_read_only_task_tools()
                 .with_todo_tool(todo_list)
                 .with_plan_tool(plan_state)
+                .with_goal_tools(self.config.goal_state.clone())
         } else {
             ToolRegistryBuilder::new()
                 .with_agent_tools(self.session.allow_shell)
                 .with_todo_tool(todo_list)
                 .with_plan_tool(plan_state)
+                .with_goal_tools(self.config.goal_state.clone())
         };
 
         builder = builder
@@ -65,6 +67,14 @@ impl Engine {
             .with_parallel_tool()
             .with_recall_archive_tool();
 
+        // SlopLedger: plan mode only gets read-only query + export,
+        // agent/yolo get the full set including append + update.
+        builder = if mode == AppMode::Plan {
+            builder.with_slop_ledger_read_only_tools()
+        } else {
+            builder.with_slop_ledger_tools()
+        };
+
         if mode != AppMode::Plan {
             builder = builder
                 .with_rlm_tool(self.deepseek_client.clone(), self.session.model.clone())
@@ -77,14 +87,9 @@ impl Engine {
         if self.config.features.enabled(Feature::WebSearch) {
             builder = builder.with_web_tools();
         }
-        // Plan mode is strictly read-only: do not expose shell execution at
-        // all, even if the session would otherwise allow it.
-        if mode != AppMode::Plan
-            && self.config.features.enabled(Feature::ShellTool)
-            && self.session.allow_shell
-        {
-            builder = builder.with_shell_tools();
-        }
+        // Shell tools (exec_shell, task_shell_start, etc.) are already gated
+        // behind `allow_shell` inside `with_agent_tools`. No separate
+        // feature-flag gate here to avoid double-registration.
 
         // Register the `remember` tool only when the user has opted in to
         // user-memory (#489). Without that opt-in the tool would always
diff --git a/crates/tui/src/core/engine/turn_loop.rs b/crates/tui/src/core/engine/turn_loop.rs
index 9f2da5ff..04c5171b 100644
--- a/crates/tui/src/core/engine/turn_loop.rs
+++ b/crates/tui/src/core/engine/turn_loop.rs
@@ -20,6 +20,11 @@ impl Engine {
         mode: AppMode,
         force_update_plan_first: bool,
     ) -> (TurnOutcomeStatus, Option<String>) {
+        // Signal to the terminal / taskbar that a turn is in progress
+        // (OSC 9 ; 4 indeterminate progress + title spinner).
+        crate::tui::notifications::set_taskbar_progress_busy();
+        crate::tui::notifications::start_title_animation("CodeWhale");
+
         let client = self
             .deepseek_client
             .clone()
@@ -30,10 +35,11 @@ impl Engine {
         let mut context_recovery_attempts = 0u8;
         let mut tool_catalog = tools.unwrap_or_default();
         if !tool_catalog.is_empty() {
-            ensure_advanced_tooling(&mut tool_catalog, mode);
+            ensure_advanced_tooling(&mut tool_catalog, mode, &self.config.tools_always_load);
         }
         let mut active_tool_names = initial_active_tools(&tool_catalog);
         let mut loop_guard = LoopGuard::default();
+        let mut goal_continuations_this_turn = 0u32;
 
         // Transparent stream-retry counter: when the chunked-transfer
         // connection dies mid-stream and we got nothing useful out of it
@@ -173,9 +179,7 @@ impl Engine {
                 continue;
             }
 
-            if let Some(input_budget) =
-                context_input_budget(&self.session.model, TURN_MAX_OUTPUT_TOKENS)
-            {
+            if let Some(input_budget) = context_input_budget(&self.session.model) {
                 let estimated_input = self.estimated_input_tokens();
                 if estimated_input > input_budget {
                     if context_recovery_attempts >= MAX_CONTEXT_RECOVERY_ATTEMPTS {
@@ -192,11 +196,7 @@ impl Engine {
                     }
 
                     if self
-                        .recover_context_overflow(
-                            &client,
-                            "preflight token budget",
-                            TURN_MAX_OUTPUT_TOKENS,
-                        )
+                        .recover_context_overflow(&client, "preflight token budget")
                         .await
                     {
                         context_recovery_attempts = context_recovery_attempts.saturating_add(1);
@@ -249,6 +249,10 @@ impl Engine {
                 let tools_ref: Option<&[crate::models::Tool]> = active_tools.as_deref();
                 match pm.check_and_update(&system_text, tools_ref) {
                     Err(change) => {
+                        let pinned_hash = pm
+                            .pinned_fingerprint()
+                            .map(|fp| fp.combined_sha256.clone())
+                            .unwrap_or_default();
                         tracing::debug!(
                             target: "prefix_cache",
                             "{}",
@@ -262,10 +266,15 @@ impl Engine {
                                 tools_changed: change.tools_changed,
                                 stability_pct: (pm.stability_ratio() * 100.0).round() as u32,
                                 changed: true,
+                                pinned_combined_hash: pinned_hash,
                             })
                             .await;
                     }
                     Ok(_) => {
+                        let pinned_hash = pm
+                            .pinned_fingerprint()
+                            .map(|fp| fp.combined_sha256.clone())
+                            .unwrap_or_default();
                         // Stable check — keep the TUI counter in sync.
                         let _ = self
                             .tx_event
@@ -275,6 +284,7 @@ impl Engine {
                                 tools_changed: false,
                                 stability_pct: (pm.stability_ratio() * 100.0).round() as u32,
                                 changed: false,
+                                pinned_combined_hash: pinned_hash,
                             })
                             .await;
                     }
@@ -326,11 +336,7 @@ impl Engine {
                     if is_context_length_error_message(&message)
                         && context_recovery_attempts < MAX_CONTEXT_RECOVERY_ATTEMPTS
                         && self
-                            .recover_context_overflow(
-                                &client,
-                                "provider context-length rejection",
-                                TURN_MAX_OUTPUT_TOKENS,
-                            )
+                            .recover_context_overflow(&client, "provider context-length rejection")
                             .await
                     {
                         context_recovery_attempts = context_recovery_attempts.saturating_add(1);
@@ -1121,6 +1127,21 @@ impl Engine {
                     continue;
                 }
 
+                if let Some(continuation) = self
+                    .goal_continuation_message_if_needed(
+                        tool_registry,
+                        &mut goal_continuations_this_turn,
+                    )
+                    .await
+                {
+                    self.add_session_message(
+                        self.user_text_message_with_turn_metadata(continuation),
+                    )
+                    .await;
+                    turn.next_step();
+                    continue;
+                }
+
                 if thinking_only_no_sendable {
                     let holding_for_subagents = {
                         let running = {
@@ -1177,6 +1198,13 @@ impl Engine {
                     "Planning tool '{tool_name}' with input: {tool_input:?}"
                 ));
 
+                let requested_tool_name = tool_name.clone();
+                let tool_def =
+                    resolve_tool_definition(&mut tool_name, &tool_catalog, tool_registry);
+                if requested_tool_name != tool_name {
+                    tool.name = tool_name.clone();
+                }
+
                 let interactive = (tool_name == "exec_shell"
                     && tool_input
                         .get("interactive")
@@ -1208,25 +1236,10 @@ impl Engine {
                     )));
                 }
 
-                let requested_tool_name = tool_name.clone();
-                let mut tool_def = tool_catalog.iter().find(|def| def.name == tool_name);
-
-                // Resolve hallucinated tool names when the model emits a
-                // non-canonical variant (Read_file, readFile, read-file, etc.).
-                if tool_def.is_none()
-                    && let Some(registry) = tool_registry
-                    && let Some(canonical) = registry.resolve(&tool_name)
-                {
-                    crate::logging::info(format!(
-                        "Resolved hallucinated tool name '{tool_name}' -> '{canonical}'"
-                    ));
-                    tool_def = tool_catalog.iter().find(|d| d.name == canonical);
-                    if tool_def.is_some() {
-                        tool_name = canonical.to_string();
-                        // Update the tool_uses entry so the result is
-                        // attributed to the canonical name.
-                        tool.name = tool_name.clone();
-                    }
+                if !command_allows_tool(self.config.allowed_tools.as_deref(), &tool_name) {
+                    blocked_error = Some(ToolError::permission_denied(format!(
+                        "Tool '{tool_name}' is not in the allowed-tools list for the current command"
+                    )));
                 }
 
                 if !caller_allowed_for_tool(tool_caller.as_ref(), tool_def) {
@@ -1685,6 +1698,7 @@ impl Engine {
                                 .send(Event::ApprovalRequired {
                                     id: tool_id.clone(),
                                     tool_name: tool_name.clone(),
+                                    input: tool_input.clone(),
                                     description: plan.approval_description.clone(),
                                     approval_key,
                                     approval_grouping_key,
@@ -1949,7 +1963,9 @@ impl Engine {
 
             if let Some(message) = loop_guard_halt {
                 crate::logging::warn(message.clone());
-                let _ = self.tx_event.send(Event::status(message)).await;
+                let _ = self.tx_event.send(Event::status(message.clone())).await;
+                // 设置 turn_error 以确保最终返回 TurnOutcomeStatus::Failed 而非 Completed
+                turn_error = Some(message);
                 break;
             }
 
@@ -2011,6 +2027,55 @@ impl Engine {
         (TurnOutcomeStatus::Completed, None)
     }
 
+    async fn goal_continuation_message_if_needed(
+        &self,
+        tool_registry: Option<&crate::tools::ToolRegistry>,
+        continuations_this_turn: &mut u32,
+    ) -> Option<String> {
+        let registry = tool_registry?;
+        if !registry.contains("update_goal") {
+            return None;
+        }
+
+        let snapshot = match self.config.goal_state.lock() {
+            Ok(state) => state.snapshot(),
+            Err(err) => {
+                tracing::warn!("goal state lock poisoned during continuation check: {err}");
+                return None;
+            }
+        };
+
+        if !snapshot.is_active() {
+            return None;
+        }
+
+        let max = crate::tools::goal::MAX_GOAL_CONTINUATIONS_PER_TURN;
+        if *continuations_this_turn >= max {
+            let _ = self
+                .tx_event
+                .send(Event::status(format!(
+                    "Goal remains active after {max} continuation pass(es); ending turn to avoid a runaway loop."
+                )))
+                .await;
+            return None;
+        }
+
+        *continuations_this_turn = (*continuations_this_turn).saturating_add(1);
+        let _ = self
+            .tx_event
+            .send(Event::status(format!(
+                "Continuing active goal audit ({}/{max})",
+                *continuations_this_turn
+            )))
+            .await;
+
+        Some(crate::tools::goal::render_continuation_prompt(
+            &snapshot,
+            *continuations_this_turn,
+            max,
+        ))
+    }
+
     pub(super) fn messages_with_turn_metadata(&self) -> Vec<Message> {
         // `<turn_meta>` is stored on user-text messages when the message is
         // appended. Do not rewrite historical messages at request time: doing
@@ -2021,8 +2086,16 @@ impl Engine {
 }
 
 fn subagent_completion_runtime_message(payload: &str) -> Message {
+    // Role is "user", not "system": some OpenAI-compatible backends apply a
+    // strict chat template (e.g. vLLM serving Qwen3) that requires any system
+    // message to be messages[0]. A system message appended mid-conversation
+    // makes the template raise "System message must be at the beginning",
+    // which surfaces as a 400 BadRequest and breaks the whole sub-agent
+    // hand-off in the parent turn. The `visibility="internal"` tag already
+    // tells the model this is a runtime event rather than user input, so the
+    // role carries no semantic weight here — only template-compatibility cost.
     Message {
-        role: "system".to_string(),
+        role: "user".to_string(),
         content: vec![ContentBlock::Text {
             text: format!(
                 "<codewhale:runtime_event kind=\"subagent_completion\" visibility=\"internal\">\n\
@@ -2042,6 +2115,40 @@ fn should_hold_turn_for_subagents(queued_completions: usize, running_children: u
     queued_completions > 0 || running_children > 0
 }
 
+fn command_allows_tool(allowed_tools: Option<&[String]>, tool_name: &str) -> bool {
+    let Some(allowed_tools) = allowed_tools else {
+        return true;
+    };
+    allowed_tools.contains(&tool_name.to_ascii_lowercase())
+}
+
+fn resolve_tool_definition<'a>(
+    tool_name: &mut String,
+    tool_catalog: &'a [Tool],
+    tool_registry: Option<&crate::tools::ToolRegistry>,
+) -> Option<&'a Tool> {
+    let mut tool_def = tool_catalog
+        .iter()
+        .find(|def| def.name.as_str() == tool_name.as_str());
+
+    // Resolve hallucinated tool names before policy gates run, so aliases like
+    // ReadFile are checked against the canonical registered tool name.
+    if tool_def.is_none()
+        && let Some(registry) = tool_registry
+        && let Some(canonical) = registry.resolve(tool_name.as_str())
+    {
+        crate::logging::info(format!(
+            "Resolved hallucinated tool name '{tool_name}' -> '{canonical}'"
+        ));
+        tool_def = tool_catalog.iter().find(|d| d.name == canonical);
+        if tool_def.is_some() {
+            *tool_name = canonical.to_string();
+        }
+    }
+
+    tool_def
+}
+
 /// Issue #1727: decide whether to surface a "thinking-only, no output" status.
 ///
 /// Reached when the assistant turn had no sendable content (no Text, no
@@ -2122,12 +2229,16 @@ mod tests {
     use super::*;
 
     #[test]
-    fn subagent_completion_handoff_is_internal_system_message() {
+    fn subagent_completion_handoff_is_internal_user_message() {
         let message = subagent_completion_runtime_message(
             "Build passed\n<codewhale:subagent.done>{\"agent_id\":\"agent_a\"}</codewhale:subagent.done>",
         );
 
-        assert_eq!(message.role, "system");
+        // Must be "user", not "system": a system message appended mid-stream
+        // trips strict chat templates (vLLM/Qwen3) into a 400 BadRequest
+        // ("System message must be at the beginning"). The internal-event
+        // framing lives in the text + visibility tag, not the role.
+        assert_eq!(message.role, "user");
         let text = match &message.content[0] {
             ContentBlock::Text { text, .. } => text,
             other => panic!("expected text block, got {other:?}"),
@@ -2309,4 +2420,45 @@ mod tests {
             "auto thinking should classify the user request, not stored metadata"
         );
     }
+
+    #[test]
+    fn allowed_tools_gate_blocks_unlisted_tool() {
+        let allowed = vec!["bash".to_string(), "grep".to_string()];
+        assert!(!command_allows_tool(Some(&allowed), "read"));
+    }
+
+    #[test]
+    fn allowed_tools_gate_allows_listed_tool_case_insensitively() {
+        let allowed = vec!["bash".to_string(), "read".to_string()];
+        assert!(command_allows_tool(Some(&allowed), "Read"));
+    }
+
+    #[test]
+    fn allowed_tools_gate_allows_all_tools_when_not_set() {
+        assert!(command_allows_tool(None, "write"));
+    }
+
+    #[test]
+    fn review_regression_allowed_tools_gate_blocks_all_tools_when_empty() {
+        let allowed = Vec::new();
+        assert!(!command_allows_tool(Some(&allowed), "bash"));
+    }
+
+    #[test]
+    fn review_regression_allowed_tools_gate_checks_canonical_tool_name() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let context = crate::tools::spec::ToolContext::new(tmp.path().to_path_buf());
+        let registry = crate::tools::ToolRegistryBuilder::new()
+            .with_file_tools()
+            .build(context);
+        let catalog = registry.to_api_tools();
+        let mut tool_name = "ReadFile".to_string();
+
+        let tool_def = resolve_tool_definition(&mut tool_name, &catalog, Some(&registry));
+
+        assert!(tool_def.is_some());
+        assert_eq!(tool_name, "read_file");
+        let allowed = vec!["read_file".to_string()];
+        assert!(command_allows_tool(Some(&allowed), &tool_name));
+    }
 }
diff --git a/crates/tui/src/core/events.rs b/crates/tui/src/core/events.rs
index b02ba2f9..0373dc04 100644
--- a/crates/tui/src/core/events.rs
+++ b/crates/tui/src/core/events.rs
@@ -114,6 +114,29 @@ pub enum Event {
         messages_after: Option<usize>,
     },
 
+    /// Context purge started.
+    PurgeStarted {
+        /// Status message for display.
+        message: String,
+    },
+
+    /// Context purge completed.
+    PurgeCompleted {
+        /// Number of messages before purge.
+        messages_before: usize,
+        /// Number of messages after purge.
+        messages_after: usize,
+        /// How many messages were removed.
+        removed_count: usize,
+        /// How many replace operations were applied.
+        replaced_count: usize,
+        /// Summary message for display.
+        message: String,
+    },
+
+    /// Context purge failed.
+    PurgeFailed { message: String },
+
     /// Context compaction failed.
     CompactionFailed {
         id: String,
@@ -226,6 +249,9 @@ pub enum Event {
         id: String,
         tool_name: String,
         description: String,
+        /// Tool parameters for approval display. Carried on the event so the
+        /// TUI does not need to reconstruct them from `pending_tool_uses`.
+        input: Value,
         /// Exact-argument fingerprint, used to scope *denials* (#1617).
         approval_key: String,
         /// Lossy / arity-aware fingerprint, used to scope *approvals* so an
@@ -281,6 +307,10 @@ pub enum Event {
         /// True when the prefix actually changed (cache invalidated).
         /// False for routine stable-check heartbeats.
         changed: bool,
+        /// Current pinned prefix combined hash (SHA-256, 64 hex chars).
+        /// Carried so `/cache stats` can surface it without reaching
+        /// into the engine's PrefixStabilityManager.
+        pinned_combined_hash: String,
     },
 }
 
diff --git a/crates/tui/src/core/ops.rs b/crates/tui/src/core/ops.rs
index a77a2625..87f47945 100644
--- a/crates/tui/src/core/ops.rs
+++ b/crates/tui/src/core/ops.rs
@@ -31,6 +31,10 @@ pub enum Op {
         auto_approve: bool,
         approval_mode: ApprovalMode,
         translation_enabled: bool,
+        show_thinking: bool,
+        /// Tool restriction from custom slash command frontmatter.
+        /// `None` means the current turn may use the normal tool set.
+        allowed_tools: Option<Vec<String>>,
     },
 
     /// Cancel the current request
@@ -76,6 +80,9 @@ pub enum Op {
     /// Run context compaction immediately.
     CompactContext,
 
+    /// Run agent-driven context purging.
+    PurgeContext,
+
     /// Edit the last user message: remove the last user+assistant exchange
     /// from the session, then re-send with the new content.
     #[allow(dead_code)]
diff --git a/crates/tui/src/core/turn.rs b/crates/tui/src/core/turn.rs
index 049bc44a..b4a551dc 100644
--- a/crates/tui/src/core/turn.rs
+++ b/crates/tui/src/core/turn.rs
@@ -128,16 +128,54 @@ fn add_optional_usage(total: Option<u32>, delta: Option<u32>) -> Option<u32> {
     }
 }
 
+/// Maximum characters of the user prompt snippet to embed in a snapshot
+/// label. Longer prompts are truncated with an ellipsis.
+const USER_PROMPT_LABEL_MAX: usize = 100;
+
+/// Format a snapshot label that includes the user prompt for readability
+/// in `/restore` listings.
+///
+/// Takes the first line of the prompt (up to `USER_PROMPT_LABEL_MAX`
+/// characters) and appends it to the traditional `type:seq` label so
+/// users can identify which turn each snapshot belongs to.
+fn format_snapshot_label(prefix: &str, turn_seq: u64, user_prompt: Option<&str>) -> String {
+    let base = format!("{prefix}:{turn_seq}");
+    match user_prompt {
+        None | Some("") => base,
+        Some(prompt) => {
+            let first_line = prompt.lines().next().unwrap_or("");
+            let truncated: String = first_line.chars().take(USER_PROMPT_LABEL_MAX).collect();
+            if truncated.chars().count() < first_line.chars().count() {
+                format!("{base}: {truncated}…")
+            } else {
+                format!("{base}: {truncated}")
+            }
+        }
+    }
+}
+
 /// Take a `pre-turn:<seq>` workspace snapshot.
 ///
 /// `cap_bytes` is the workspace-size ceiling that gates first-init
 /// (passed through to [`SnapshotRepo::open_or_init_with_cap`]); pass
 /// `0` to disable the cap.
+/// `user_prompt` is an optional snippet of the user's message for this
+/// turn, embedded in the snapshot label so `/restore` listings are
+/// human-readable.
 ///
 /// Returns the snapshot SHA on success, `None` on any error. Errors are
 /// logged at WARN; the turn loop must not block on this.
-pub fn pre_turn_snapshot(workspace: &Path, turn_seq: u64, cap_bytes: u64) -> Option<String> {
-    snapshot_with_label(workspace, &format!("pre-turn:{turn_seq}"), cap_bytes)
+pub fn pre_turn_snapshot(
+    workspace: &Path,
+    turn_seq: u64,
+    cap_bytes: u64,
+    user_prompt: Option<&str>,
+) -> Option<String> {
+    snapshot_with_label(
+        workspace,
+        &format_snapshot_label("pre-turn", turn_seq, user_prompt),
+        cap_bytes,
+    )
 }
 
 /// Take a `tool:<call_id>` workspace snapshot, taken before executing a
@@ -154,8 +192,17 @@ pub fn pre_tool_snapshot(workspace: &Path, call_id: &str, cap_bytes: u64) -> Opt
 
 /// Take a `post-turn:<seq>` workspace snapshot. Same failure model as
 /// [`pre_turn_snapshot`].
-pub fn post_turn_snapshot(workspace: &Path, turn_seq: u64, cap_bytes: u64) -> Option<String> {
-    snapshot_with_label(workspace, &format!("post-turn:{turn_seq}"), cap_bytes)
+pub fn post_turn_snapshot(
+    workspace: &Path,
+    turn_seq: u64,
+    cap_bytes: u64,
+    user_prompt: Option<&str>,
+) -> Option<String> {
+    snapshot_with_label(
+        workspace,
+        &format_snapshot_label("post-turn", turn_seq, user_prompt),
+        cap_bytes,
+    )
 }
 
 fn snapshot_with_label(workspace: &Path, label: &str, cap_bytes: u64) -> Option<String> {
diff --git a/crates/tui/src/cycle_manager.rs b/crates/tui/src/cycle_manager.rs
index cfbe2a17..c7315053 100644
--- a/crates/tui/src/cycle_manager.rs
+++ b/crates/tui/src/cycle_manager.rs
@@ -284,7 +284,7 @@ impl StructuredState {
                 let marker = match item.status {
                     crate::tools::todo::TodoStatus::Pending => "[ ]",
                     crate::tools::todo::TodoStatus::InProgress => "[~]",
-                    crate::tools::todo::TodoStatus::Completed => "[x]",
+                    crate::tools::todo::TodoStatus::Completed => "[✓]",
                 };
                 out.push_str(&format!("- {marker} {}\n", item.content));
             }
@@ -299,7 +299,7 @@ impl StructuredState {
                 let marker = match item.status {
                     crate::tools::plan::StepStatus::Pending => "[ ]",
                     crate::tools::plan::StepStatus::InProgress => "[~]",
-                    crate::tools::plan::StepStatus::Completed => "[x]",
+                    crate::tools::plan::StepStatus::Completed => "[✓]",
                 };
                 out.push_str(&format!("- {marker} {}\n", item.step));
             }
@@ -463,14 +463,16 @@ pub struct CycleArchiveHeader {
     pub message_count: usize,
 }
 
-/// Resolve the on-disk archive directory: `~/.deepseek/sessions/<id>/cycles`.
+/// Resolve the on-disk archive directory: `~/.codewhale/sessions/<id>/cycles`
+/// (or legacy `~/.deepseek/sessions/<id>/cycles`).
 fn archive_dir_for(session_id: &str) -> Result<PathBuf> {
-    let home = dirs::home_dir().context("Could not resolve home directory for cycle archive")?;
-    Ok(home
-        .join(".deepseek")
-        .join("sessions")
-        .join(session_id)
-        .join("cycles"))
+    let sessions = codewhale_config::resolve_state_dir("sessions").unwrap_or_else(|_| {
+        dirs::home_dir()
+            .unwrap_or_else(|| PathBuf::from("."))
+            .join(".deepseek")
+            .join("sessions")
+    });
+    Ok(sessions.join(session_id).join("cycles"))
 }
 
 /// Archive a cycle's messages to JSONL on disk and return the path written.
diff --git a/crates/tui/src/eval.rs b/crates/tui/src/eval.rs
index 5d095254..d3651613 100644
--- a/crates/tui/src/eval.rs
+++ b/crates/tui/src/eval.rs
@@ -11,26 +11,17 @@ use std::collections::BTreeMap;
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
-use std::process::Command;
 use std::time::{Duration, Instant};
 use tempfile::TempDir;
 
+#[cfg(test)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum EvalShellPlatform {
     Windows,
     Unix,
 }
 
-impl EvalShellPlatform {
-    fn current() -> Self {
-        if cfg!(windows) {
-            Self::Windows
-        } else {
-            Self::Unix
-        }
-    }
-}
-
+#[cfg(test)]
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct EvalShellInvocation {
     program: &'static str,
@@ -38,10 +29,7 @@ struct EvalShellInvocation {
     raw_payload_on_windows: bool,
 }
 
-fn eval_shell_invocation(command: &str) -> EvalShellInvocation {
-    eval_shell_invocation_for_platform(command, EvalShellPlatform::current())
-}
-
+#[cfg(test)]
 fn eval_shell_invocation_for_platform(
     command: &str,
     platform: EvalShellPlatform,
@@ -60,24 +48,6 @@ fn eval_shell_invocation_for_platform(
     }
 }
 
-fn push_eval_shell_args(cmd: &mut Command, invocation: &EvalShellInvocation) {
-    #[cfg(windows)]
-    {
-        use std::os::windows::process::CommandExt;
-        if invocation.raw_payload_on_windows
-            && invocation.program.eq_ignore_ascii_case("cmd")
-            && invocation.args.len() == 2
-            && invocation.args[0].eq_ignore_ascii_case("/C")
-        {
-            cmd.raw_arg(&invocation.args[0]);
-            cmd.raw_arg(&invocation.args[1]);
-            return;
-        }
-    }
-
-    cmd.args(&invocation.args);
-}
-
 /// Representative tool steps covered by the evaluation harness.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
 pub enum ScenarioStepKind {
@@ -767,25 +737,7 @@ fn apply_patch(root: &Path, patch: &str) -> Result<()> {
 }
 
 fn exec_shell(root: &Path, command: &str) -> Result<String> {
-    let invocation = eval_shell_invocation(command);
-    let mut cmd = Command::new(invocation.program);
-    push_eval_shell_args(&mut cmd, &invocation);
-    let output = cmd
-        .current_dir(root)
-        .output()
-        .with_context(|| format!("failed to execute shell command: {command}"))?;
-
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        return Err(anyhow!(
-            "shell command failed (status={}): {}",
-            output.status,
-            stderr.trim()
-        ));
-    }
-
-    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
-    Ok(stdout.trim().to_string())
+    crate::shell_dispatcher::global_dispatcher().run_foreground(command, root)
 }
 
 fn truncate_output(value: &str, max_chars: usize) -> String {
diff --git a/crates/tui/src/llm_client/mock.rs b/crates/tui/src/llm_client/mock.rs
index 2588755d..8dc4043e 100644
--- a/crates/tui/src/llm_client/mock.rs
+++ b/crates/tui/src/llm_client/mock.rs
@@ -63,6 +63,21 @@ use super::{LlmClient, StreamEventBox};
 /// the mock does not require `MessageStart` to be present.
 pub type CannedTurn = Vec<StreamEvent>;
 
+/// A queued mock response step.
+pub enum FauxStep {
+    Canned(CannedTurn),
+    /// Build a canned turn from the live outgoing request.
+    ///
+    /// Tests can assert DeepSeek V4's thinking-mode tool-call invariant here:
+    /// on the assistant turn that produced the previous tool call, the next
+    /// outgoing request must still carry `reasoning_content` (represented in
+    /// this model as a [`ContentBlock::Thinking`] block). If it is missing,
+    /// DeepSeek V4 returns HTTP 400 on the follow-up turn. This guards the
+    /// [v0.4.9-v0.5.1 regression range](https://github.com/Hmbown/CodeWhale/compare/v0.4.9...v0.5.1)
+    /// where that content was dropped.
+    Factory(Box<dyn Fn(&MessageRequest) -> CannedTurn + Send + Sync>),
+}
+
 /// A queue-driven mock LLM client.
 ///
 /// The mock holds a FIFO queue of canned response turns. Each call to
@@ -75,7 +90,7 @@ pub type CannedTurn = Vec<StreamEvent>;
 /// can assert on the outgoing payload (e.g. that prior `reasoning_content` is
 /// preserved across turns).
 pub struct MockLlmClient {
-    canned: Mutex<VecDeque<CannedTurn>>,
+    canned: Mutex<VecDeque<FauxStep>>,
     captured_requests: Mutex<Vec<MessageRequest>>,
     calls: AtomicUsize,
     provider_name: &'static str,
@@ -91,7 +106,7 @@ impl MockLlmClient {
     #[must_use]
     pub fn new(canned: Vec<CannedTurn>) -> Self {
         Self {
-            canned: Mutex::new(canned.into()),
+            canned: Mutex::new(canned.into_iter().map(FauxStep::Canned).collect()),
             captured_requests: Mutex::new(Vec::new()),
             calls: AtomicUsize::new(0),
             provider_name: "mock",
@@ -119,7 +134,22 @@ impl MockLlmClient {
         self.canned
             .lock()
             .expect("MockLlmClient.canned mutex poisoned")
-            .push_back(turn);
+            .push_back(FauxStep::Canned(turn));
+    }
+
+    /// Push a factory step onto the back of the queue.
+    ///
+    /// The closure receives the live outgoing [`MessageRequest`] before the
+    /// response stream is built, so assertions panic directly from the client
+    /// call rather than later while polling the returned stream.
+    pub fn push_factory<F>(&self, factory: F)
+    where
+        F: Fn(&MessageRequest) -> CannedTurn + Send + Sync + 'static,
+    {
+        self.canned
+            .lock()
+            .expect("MockLlmClient.canned mutex poisoned")
+            .push_back(FauxStep::Factory(Box::new(factory)));
     }
 
     /// Push a canned non-streaming `MessageResponse`. Consumed by
@@ -175,13 +205,20 @@ impl MockLlmClient {
         self.calls.fetch_add(1, Ordering::SeqCst);
     }
 
-    fn pop_turn(&self) -> Option<CannedTurn> {
+    fn pop_step(&self) -> Option<FauxStep> {
         self.canned
             .lock()
             .expect("MockLlmClient.canned mutex poisoned")
             .pop_front()
     }
 
+    fn turn_from_step(&self, step: FauxStep, request: &MessageRequest) -> CannedTurn {
+        match step {
+            FauxStep::Canned(turn) => turn,
+            FauxStep::Factory(factory) => factory(request),
+        }
+    }
+
     fn pop_message(&self) -> Option<MessageResponse> {
         self.canned_messages
             .lock()
@@ -207,26 +244,28 @@ impl LlmClient for MockLlmClient {
         }
 
         // Fallback: synthesize a MessageResponse from the next streaming turn.
-        let Some(turn) = self.pop_turn() else {
+        let Some(step) = self.pop_step() else {
             return Err(anyhow!(
                 "MockLlmClient: create_message called but no canned response queued (request #{})",
                 self.calls.load(Ordering::SeqCst)
             ));
         };
 
+        let turn = self.turn_from_step(step, &request);
         Ok(synthesize_message_response(turn, &self.model))
     }
 
     async fn create_message_stream(&self, request: MessageRequest) -> Result<StreamEventBox> {
         self.record_request(&request);
 
-        let Some(turn) = self.pop_turn() else {
+        let Some(step) = self.pop_step() else {
             return Err(anyhow!(
                 "MockLlmClient: create_message_stream called but no canned turn queued (call #{})",
                 self.calls.load(Ordering::SeqCst)
             ));
         };
 
+        let turn = self.turn_from_step(step, &request);
         Ok(stream_from_canned(turn))
     }
 
@@ -561,6 +600,22 @@ mod tests {
         assert_eq!(resp.stop_reason.as_deref(), Some("end_turn"));
     }
 
+    #[tokio::test]
+    async fn create_message_synthesizes_from_factory_turn() {
+        let mock = MockLlmClient::new(Vec::new());
+        mock.push_factory(|request| {
+            assert_eq!(request.model, "mock-model");
+            canned::simple_text_turn("from factory")
+        });
+
+        let resp = mock.create_message(empty_request()).await.unwrap();
+        let text = match &resp.content[0] {
+            ContentBlock::Text { text, .. } => text.clone(),
+            _ => panic!("expected text"),
+        };
+        assert_eq!(text, "from factory");
+    }
+
     #[tokio::test]
     async fn provider_and_model_are_overridable() {
         let mock = MockLlmClient::new(vec![canned::simple_text_turn("x")])
diff --git a/crates/tui/src/localization.rs b/crates/tui/src/localization.rs
index 874bb2ec..645c758c 100644
--- a/crates/tui/src/localization.rs
+++ b/crates/tui/src/localization.rs
@@ -39,6 +39,7 @@ pub enum Locale {
     ZhHant,
     PtBr,
     Es419,
+    Vi,
 }
 
 impl Locale {
@@ -50,6 +51,7 @@ impl Locale {
             Self::ZhHant => "zh-Hant",
             Self::PtBr => "pt-BR",
             Self::Es419 => "es-419",
+            Self::Vi => "vi",
         }
     }
 
@@ -61,6 +63,7 @@ impl Locale {
             Self::ZhHant => "Traditional Chinese (繁體中文)",
             Self::PtBr => "Brazilian Portuguese (Português do Brasil)",
             Self::Es419 => "Latin American Spanish (Español latinoamericano)",
+            Self::Vi => "Vietnamese (Tiếng Việt)",
         }
     }
 
@@ -115,6 +118,14 @@ impl Locale {
                 fallback: "en",
                 coverage: LocaleCoverage::V076Core,
             },
+            Self::Vi => LocaleSpec {
+                tag: "vi",
+                display_name: "Vietnamese",
+                script: "Latin",
+                direction: TextDirection::Ltr,
+                fallback: "en",
+                coverage: LocaleCoverage::V076Core,
+            },
         }
     }
 
@@ -127,6 +138,7 @@ impl Locale {
             Self::ZhHant,
             Self::PtBr,
             Self::Es419,
+            Self::Vi,
         ]
     }
 }
@@ -165,14 +177,6 @@ pub const PLANNED_QA_LOCALES: &[LocaleSpec] = &[
         fallback: "en",
         coverage: LocaleCoverage::PlannedQa,
     },
-    LocaleSpec {
-        tag: "vi",
-        display_name: "Vietnamese",
-        script: "Latin",
-        direction: TextDirection::Ltr,
-        fallback: "en",
-        coverage: LocaleCoverage::PlannedQa,
-    },
     LocaleSpec {
         tag: "sw",
         display_name: "Swahili",
@@ -255,6 +259,7 @@ pub enum MessageId {
     CmdBalanceDescription,
     CmdClearDescription,
     CmdCompactDescription,
+    CmdPurgeDescription,
     CmdConfigDescription,
     CmdContextDescription,
     CmdCostDescription,
@@ -294,10 +299,12 @@ pub enum MessageId {
     CmdRlmDescription,
     CmdSaveDescription,
     CmdForkDescription,
+    CmdNewDescription,
     CmdSessionsDescription,
     CmdSettingsDescription,
     CmdSkillDescription,
     CmdSkillsDescription,
+    CmdSlopDescription,
     CmdStashDescription,
     CmdStatusDescription,
     CmdStatuslineDescription,
@@ -454,6 +461,32 @@ pub enum MessageId {
     OnboardTipsLine4,
     OnboardTipsFooterEnter,
     OnboardTipsFooterAction,
+    // Context menu.
+    CtxMenuTitle,
+    CtxMenuCopySelection,
+    CtxMenuCopySelectionDesc,
+    CtxMenuOpenSelection,
+    CtxMenuOpenSelectionDesc,
+    CtxMenuClearSelection,
+    CtxMenuOpenDetails,
+    CtxMenuCopyMessage,
+    CtxMenuCopyMessageDesc,
+    CtxMenuOpenInEditor,
+    CtxMenuOpenInEditorDesc,
+    CtxMenuShowCell,
+    CtxMenuShowCellDesc,
+    CtxMenuHideCell,
+    CtxMenuHideCellDesc,
+    CtxMenuShowHidden,
+    CtxMenuShowHiddenDesc,
+    CtxMenuPaste,
+    CtxMenuPasteDesc,
+    CtxMenuCmdPalette,
+    CtxMenuCmdPaletteDesc,
+    CtxMenuContextInspector,
+    CtxMenuContextInspectorDesc,
+    CtxMenuHelp,
+    CtxMenuHelpDesc,
 }
 
 #[allow(dead_code)]
@@ -491,6 +524,7 @@ pub const ALL_MESSAGE_IDS: &[MessageId] = &[
     MessageId::CmdCacheDescription,
     MessageId::CmdClearDescription,
     MessageId::CmdCompactDescription,
+    MessageId::CmdPurgeDescription,
     MessageId::CmdConfigDescription,
     MessageId::CmdContextDescription,
     MessageId::CmdCostDescription,
@@ -527,10 +561,12 @@ pub const ALL_MESSAGE_IDS: &[MessageId] = &[
     MessageId::CmdReviewDescription,
     MessageId::CmdRlmDescription,
     MessageId::CmdSaveDescription,
+    MessageId::CmdNewDescription,
     MessageId::CmdSessionsDescription,
     MessageId::CmdSettingsDescription,
     MessageId::CmdSkillDescription,
     MessageId::CmdSkillsDescription,
+    MessageId::CmdSlopDescription,
     MessageId::CmdStashDescription,
     MessageId::CmdStatusDescription,
     MessageId::CmdStatuslineDescription,
@@ -688,6 +724,32 @@ pub const ALL_MESSAGE_IDS: &[MessageId] = &[
     MessageId::OnboardTipsLine4,
     MessageId::OnboardTipsFooterEnter,
     MessageId::OnboardTipsFooterAction,
+    // Context menu.
+    MessageId::CtxMenuTitle,
+    MessageId::CtxMenuCopySelection,
+    MessageId::CtxMenuCopySelectionDesc,
+    MessageId::CtxMenuOpenSelection,
+    MessageId::CtxMenuOpenSelectionDesc,
+    MessageId::CtxMenuClearSelection,
+    MessageId::CtxMenuOpenDetails,
+    MessageId::CtxMenuCopyMessage,
+    MessageId::CtxMenuCopyMessageDesc,
+    MessageId::CtxMenuOpenInEditor,
+    MessageId::CtxMenuOpenInEditorDesc,
+    MessageId::CtxMenuShowCell,
+    MessageId::CtxMenuShowCellDesc,
+    MessageId::CtxMenuHideCell,
+    MessageId::CtxMenuHideCellDesc,
+    MessageId::CtxMenuShowHidden,
+    MessageId::CtxMenuShowHiddenDesc,
+    MessageId::CtxMenuPaste,
+    MessageId::CtxMenuPasteDesc,
+    MessageId::CtxMenuCmdPalette,
+    MessageId::CtxMenuCmdPaletteDesc,
+    MessageId::CtxMenuContextInspector,
+    MessageId::CtxMenuContextInspectorDesc,
+    MessageId::CtxMenuHelp,
+    MessageId::CtxMenuHelpDesc,
 ];
 
 pub fn tr(locale: Locale, id: MessageId) -> &'static str {
@@ -702,6 +764,7 @@ pub fn thinking_translation_placeholder(locale: Locale) -> &'static str {
         Locale::ZhHant => "正在思考，完成後翻譯為繁體中文...",
         Locale::PtBr => "Pensando; traduzindo ao concluir...",
         Locale::Es419 => "Pensando; traduciendo al finalizar...",
+        Locale::Vi => "Đang suy nghĩ; sẽ dịch sau khi hoàn thành...",
     }
 }
 
@@ -713,6 +776,7 @@ pub fn thinking_translation_in_progress(locale: Locale) -> &'static str {
         Locale::ZhHant => "正在翻譯思考內容...",
         Locale::PtBr => "Traduzindo o conteúdo de raciocínio...",
         Locale::Es419 => "Traduciendo el contenido de razonamiento...",
+        Locale::Vi => "Đang dịch nội dung suy nghĩ...",
     }
 }
 
@@ -724,6 +788,7 @@ pub fn thinking_translation_complete(locale: Locale) -> &'static str {
         Locale::ZhHant => "思考內容翻譯完成",
         Locale::PtBr => "Tradução do raciocínio concluída",
         Locale::Es419 => "Traducción del razonamiento completada",
+        Locale::Vi => "Đã dịch xong nội dung suy nghĩ",
     }
 }
 
@@ -735,6 +800,7 @@ pub fn thinking_translation_failed(locale: Locale) -> &'static str {
         Locale::ZhHant => "思考內容翻譯失敗",
         Locale::PtBr => "Falha ao traduzir o raciocínio",
         Locale::Es419 => "Falló la traducción del razonamiento",
+        Locale::Vi => "Dịch nội dung suy nghĩ thất bại",
     }
 }
 
@@ -746,6 +812,7 @@ pub fn hidden_translation_failed(locale: Locale) -> &'static str {
         Locale::ZhHant => "翻譯失敗，原文已隱藏。",
         Locale::PtBr => "A tradução falhou; o texto original está oculto.",
         Locale::Es419 => "La traducción falló; el texto original está oculto.",
+        Locale::Vi => "Dịch thất bại; văn bản gốc đã bị ẩn.",
     }
 }
 
@@ -855,6 +922,9 @@ fn parse_locale(value: &str) -> Option<Locale> {
     if value.starts_with("es") {
         return Some(Locale::Es419);
     }
+    if value.starts_with("vi") {
+        return Some(Locale::Vi);
+    }
     None
 }
 
@@ -922,6 +992,9 @@ fn english(id: MessageId) -> &'static str {
         MessageId::CmdCompactDescription => {
             "Trigger context compaction to free up space (legacy; v0.6.6 prefers cycle restart)"
         }
+        MessageId::CmdPurgeDescription => {
+            "Let the agent surgically prune conversation history to free context space"
+        }
         MessageId::CmdConfigDescription => "Open interactive configuration editor",
         MessageId::CmdContextDescription => "Open compact session context inspector",
         MessageId::CmdCostDescription => "Show session cost breakdown",
@@ -957,7 +1030,7 @@ fn english(id: MessageId) -> &'static str {
         MessageId::CmdNoteDescription => "Add, list, edit, or remove workspace notes",
         MessageId::CmdThemeDescription => "Switch theme or open the theme picker",
         MessageId::CmdProviderDescription => {
-            "Switch or view the active LLM backend (codewhale | nvidia-nim | ollama)"
+            "Switch or view the active LLM backend (deepseek | nvidia-nim | ollama)"
         }
         MessageId::CmdQueueDescription => "View or edit queued messages",
         MessageId::CmdRecallDescription => "Search prior cycle archives (BM25 over message text)",
@@ -971,6 +1044,7 @@ fn english(id: MessageId) -> &'static str {
         MessageId::CmdRlmDescription => "Open a persistent RLM context: /rlm [0-3] <file_or_text>",
         MessageId::CmdSaveDescription => "Save session to file",
         MessageId::CmdForkDescription => "Fork the active conversation into a sibling session",
+        MessageId::CmdNewDescription => "Start a fresh saved session",
         MessageId::CmdSessionsDescription => "Open session history picker",
         MessageId::CmdSettingsDescription => "Show persistent settings",
         MessageId::CmdSkillDescription => {
@@ -979,6 +1053,7 @@ fn english(id: MessageId) -> &'static str {
         MessageId::CmdSkillsDescription => {
             "List local skills (filter by `/skills <prefix>`; --remote browses the curated registry)"
         }
+        MessageId::CmdSlopDescription => "Inspect or export the SlopLedger",
         MessageId::CmdStashDescription => {
             "Park or restore a composer draft (Ctrl+S to push, /stash list/pop)"
         }
@@ -1169,7 +1244,7 @@ fn english(id: MessageId) -> &'static str {
             "Pick the UI language. You can change it any time with `/settings set locale <tag>`."
         }
         MessageId::OnboardLanguageFooter => {
-            "Press 1-6 to choose, or Enter to keep the current setting"
+            "Press 1-7 to choose, or Enter to keep the current setting"
         }
         // Onboarding — API key entry.
         MessageId::OnboardApiKeyTitle => "Connect your DeepSeek API key",
@@ -1215,6 +1290,32 @@ fn english(id: MessageId) -> &'static str {
         }
         MessageId::OnboardTipsFooterEnter => "Press Enter",
         MessageId::OnboardTipsFooterAction => " to open the workspace",
+        // Context menu.
+        MessageId::CtxMenuTitle => " Right click ",
+        MessageId::CtxMenuCopySelection => "Copy selection",
+        MessageId::CtxMenuCopySelectionDesc => "write selected transcript text",
+        MessageId::CtxMenuOpenSelection => "Open selection",
+        MessageId::CtxMenuOpenSelectionDesc => "show selected text in pager",
+        MessageId::CtxMenuClearSelection => "Clear selection",
+        MessageId::CtxMenuOpenDetails => "Open details",
+        MessageId::CtxMenuCopyMessage => "Copy message",
+        MessageId::CtxMenuCopyMessageDesc => "write clicked transcript cell",
+        MessageId::CtxMenuOpenInEditor => "Open in editor",
+        MessageId::CtxMenuOpenInEditorDesc => "open file:line in $EDITOR",
+        MessageId::CtxMenuShowCell => "Show cell",
+        MessageId::CtxMenuShowCellDesc => "unhide this transcript cell",
+        MessageId::CtxMenuHideCell => "Hide cell",
+        MessageId::CtxMenuHideCellDesc => "collapse this transcript cell",
+        MessageId::CtxMenuShowHidden => "Show hidden",
+        MessageId::CtxMenuShowHiddenDesc => "unhide all collapsed cells",
+        MessageId::CtxMenuPaste => "Paste",
+        MessageId::CtxMenuPasteDesc => "insert clipboard into composer",
+        MessageId::CtxMenuCmdPalette => "Command palette",
+        MessageId::CtxMenuCmdPaletteDesc => "commands, skills, and tools",
+        MessageId::CtxMenuContextInspector => "Context inspector",
+        MessageId::CtxMenuContextInspectorDesc => "active context and cache hints",
+        MessageId::CtxMenuHelp => "Help",
+        MessageId::CtxMenuHelpDesc => "keybindings and commands",
     }
 }
 
@@ -1226,9 +1327,432 @@ fn translation(locale: Locale, id: MessageId) -> Option<&'static str> {
         Locale::ZhHant => traditional_chinese(id),
         Locale::PtBr => portuguese_brazil(id),
         Locale::Es419 => spanish_latin_america(id),
+        Locale::Vi => vietnamese(id),
     }
 }
 
+fn vietnamese(id: MessageId) -> Option<&'static str> {
+    Some(match id {
+        MessageId::ComposerPlaceholder => "Nhập nhiệm vụ hoặc sử dụng /.",
+        MessageId::HistorySearchPlaceholder => "Tìm kiếm lịch sử câu lệnh...",
+        MessageId::HistorySearchTitle => "Tìm kiếm lịch sử",
+        MessageId::HistoryHintMove => "Lên/Xuống để di chuyển",
+        MessageId::HistoryHintAccept => "Enter để chấp nhận",
+        MessageId::HistoryHintRestore => "Esc để khôi phục",
+        MessageId::HistoryNoMatches => "  Không tìm thấy kết quả",
+        MessageId::ConfigTitle => "Cấu hình phiên làm việc",
+        MessageId::ConfigModalTitle => " Cấu hình ",
+        MessageId::ConfigSearchPlaceholder => "Nhập để lọc kết quả",
+        MessageId::ConfigNoSettings => "  Không có cài đặt nào khả dụng.",
+        MessageId::ConfigNoMatchesPrefix => "  Không có cài đặt nào khớp với ",
+        MessageId::ConfigFilteredSettings => "  Cài đặt đã lọc",
+        MessageId::ConfigShowing => "  Đang hiển thị",
+        MessageId::ConfigFooterDefault => " gõ=lọc, Lên/Xuống=chọn, Enter/e=sửa, Esc/q=đóng ",
+        MessageId::ConfigFooterScrollable => {
+            " gõ=lọc, Lên/Xuống=chọn, Enter/e=sửa, PgUp/PgDn=cuộn, Esc/q=đóng "
+        }
+        MessageId::ConfigFooterFiltered => {
+            " gõ=lọc, Backspace=xóa, Ctrl+U/Esc=xóa sạch, Enter=sửa "
+        }
+        MessageId::HelpTitle => "Trợ giúp",
+        MessageId::HelpFilterPlaceholder => "Nhập để lọc",
+        MessageId::HelpFilterPrefix => "Bộ lọc: ",
+        MessageId::HelpNoMatches => "  Không tìm thấy kết quả.",
+        MessageId::HelpSlashCommands => "Các lệnh bắt đầu bằng dấu gạch chéo (/)",
+        MessageId::HelpKeybindings => "Phím tắt",
+        MessageId::HelpFooterTypeFilter => " nhập để lọc ",
+        MessageId::HelpFooterMove => "  Lên/Xuống để di chuyển ",
+        MessageId::HelpFooterJump => " PgUp/PgDn để nhảy trang ",
+        MessageId::HelpFooterClose => " Esc để đóng ",
+        MessageId::CmdAnchorDescription => {
+            "Ghim một dữ kiện không bị ảnh hưởng khi nén (tự động đưa vào ngữ cảnh)"
+        }
+        MessageId::CmdAttachDescription => {
+            "Đính kèm hình ảnh/video; sử dụng @path cho tệp văn bản hoặc thư mục"
+        }
+        MessageId::CmdCacheDescription => {
+            "Hiển thị thống kê hit/miss của bộ nhớ đệm tiền tố DeepSeek trong N lượt gần nhất"
+        }
+        MessageId::CmdChangeDescription => "Hiển thị thông tin nhật ký thay đổi mới nhất",
+        MessageId::CmdChangeHeader => "Nhật Ký Thay Đổi Mới Nhất",
+        MessageId::CmdChangeTranslationQueued => {
+            "Ghi chú phát hành bằng tiếng Anh hiển thị bên dưới. Bản dịch sẽ được yêu cầu tiếp theo; nếu nhà cung cấp không khả dụng, văn bản tiếng Anh này sẽ được dùng làm dự phòng."
+        }
+        MessageId::CmdChangeTranslationUnavailable => {
+            "Ghi chú phát hành bằng tiếng Anh hiển thị bên dưới. Bản dịch không khả dụng vì phiên hiện tại không có mã khóa API hoặc đang ngoại tuyến."
+        }
+        MessageId::CmdChangePreviousVersion => {
+            "Phiên bản trước: {version} — chạy `/change {version}` để xem"
+        }
+        MessageId::CmdBalanceDescription => {
+            "Kiểm tra số dư tài khoản của nhà cung cấp dịch vụ đang hoạt động"
+        }
+        MessageId::CmdClearDescription => "Xóa lịch sử trò chuyện",
+        MessageId::CmdCompactDescription => {
+            "Kích hoạt nén ngữ cảnh để giải phóng không gian (cũ; v0.6.6 ưu tiên khởi động lại chu kỳ)"
+        }
+        MessageId::CmdPurgeDescription => {
+            "Cho agent cắt gọn lịch sử trò chuyện để giải phóng ngữ cảnh"
+        }
+        MessageId::CmdConfigDescription => "Mở trình chỉnh sửa cấu hình tương tác",
+        MessageId::CmdContextDescription => "Mở trình kiểm tra ngữ cảnh phiên thu gọn",
+        MessageId::CmdCostDescription => "Hiển thị chi tiết chi phí của phiên làm việc",
+        MessageId::CmdCycleDescription => "Hiển thị báo cáo chuyển tiếp cho một chu kỳ cụ thể",
+        MessageId::CmdCyclesDescription => {
+            "Liệt kê các lần bàn giao chu kỳ checkpoint-restart trong phiên này"
+        }
+        MessageId::CmdDiffDescription => "Hiển thị các thay đổi của tệp kể từ khi bắt đầu phiên",
+        MessageId::CmdEditDescription => "Chỉnh sửa và gửi lại tin nhắn gần nhất",
+        MessageId::CmdExitDescription => "Thoát ứng dụng",
+        MessageId::CmdExportDescription => "Xuất cuộc trò chuyện sang định dạng Markdown",
+        MessageId::CmdFeedbackDescription => "Tạo một URL để gửi phản hồi trên GitHub",
+        MessageId::CmdHelpDescription => "Hiển thị thông tin trợ giúp",
+        MessageId::CmdHomeDescription => {
+            "Hiển thị bảng điều khiển trang chủ với số liệu thống kê và hành động nhanh"
+        }
+        MessageId::CmdHooksDescription => "Liệt kê các lifecycle hook đã cấu hình (chỉ đọc)",
+        MessageId::CmdAgentDescription => "Mở một phiên sub-agent nền: /agent [0-3] <nhiệm_vụ>",
+        MessageId::CmdGoalDescription => "Đặt mục tiêu cho phiên với giới hạn token tùy chọn",
+        MessageId::CmdInitDescription => "Tạo tệp AGENTS.md cho dự án",
+        MessageId::CmdLspDescription => "Bật hoặc tắt tính năng chẩn đoán LSP",
+        MessageId::CmdShareDescription => {
+            "Xuất phiên hiện tại thành một liên kết web có thể chia sẻ"
+        }
+        MessageId::CmdJobsDescription => "Kiểm tra và kiểm soát các lệnh chạy ngầm",
+        MessageId::CmdLinksDescription => {
+            "Hiển thị các liên kết đến bảng điều khiển và tài liệu của DeepSeek"
+        }
+        MessageId::CmdLoadDescription => "Tải phiên làm việc từ tệp",
+        MessageId::CmdLogoutDescription => "Xóa khóa API và quay lại bước thiết lập",
+        MessageId::CmdMcpDescription => "Mở hoặc quản lý các máy chủ MCP",
+        MessageId::CmdMemoryDescription => "Kiểm tra hoặc quản lý tệp bộ nhớ người dùng liên tục",
+        MessageId::CmdModeDescription => {
+            "Chuyển đổi chế độ hoặc mở bảng chọn: /mode [agent|plan|yolo|1|2|3]"
+        }
+        MessageId::CmdModelDescription => "Chuyển đổi hoặc xem mô hình AI hiện tại",
+        MessageId::CmdModelsDescription => "Liệt kê các mô hình khả dụng từ API",
+        MessageId::CmdNetworkDescription => "Quản lý các quy tắc cho phép và từ chối mạng",
+        MessageId::CmdNoteDescription => {
+            "Thêm, liệt kê, sửa hoặc xóa ghi chú trong không gian làm việc"
+        }
+        MessageId::CmdThemeDescription => "Chuyển đổi giao diện hoặc mở bảng chọn giao diện",
+        MessageId::CmdProviderDescription => {
+            "Chuyển đổi hoặc xem backend LLM đang hoạt động (deepseek | nvidia-nim | ollama)"
+        }
+        MessageId::CmdQueueDescription => "Xem hoặc chỉnh sửa các tin nhắn đang chờ xử lý",
+        MessageId::CmdRecallDescription => {
+            "Tìm kiếm kho lưu trữ chu kỳ trước (BM25 trên văn bản tin nhắn)"
+        }
+        MessageId::CmdRelayDescription => "Tạo một phiên tiếp sức cho một luồng mới",
+        MessageId::CmdRenameDescription => "Đổi tên phiên làm việc hiện tại",
+        MessageId::CmdRestoreDescription => {
+            "Khôi phục không gian làm việc về bản chụp trước/sau lượt. Nếu không có đối số, hiển thị các bản chụp gần đây."
+        }
+        MessageId::CmdRetryDescription => "Thử lại yêu cầu gần nhất",
+        MessageId::CmdReviewDescription => {
+            "Chạy một quy trình xem xét mã nguồn có cấu trúc trên tệp, diff hoặc PR"
+        }
+        MessageId::CmdRlmDescription => {
+            "Mở một ngữ cảnh RLM liên tục: /rlm [0-3] <tệp_hoặc_văn_bản>"
+        }
+        MessageId::CmdSaveDescription => "Lưu phiên làm việc vào tệp",
+        MessageId::CmdForkDescription => {
+            "Rẽ nhánh (fork) cuộc hội thoại hiện tại thành một phiên song song"
+        }
+        MessageId::CmdNewDescription => "Bắt đầu một phiên lưu mới",
+        MessageId::CmdSessionsDescription => "Mở bảng chọn lịch sử phiên làm việc",
+        MessageId::CmdSettingsDescription => "Hiển thị các cài đặt liên tục",
+        MessageId::CmdSkillDescription => {
+            "Kích hoạt một kỹ năng, hoặc cài đặt/cập nhật/gỡ bỏ/tin cậy một kỹ năng cộng đồng"
+        }
+        MessageId::CmdSkillsDescription => {
+            "Liệt kê các kỹ năng cục bộ (lọc bằng `/skills <tiền_tố>`; --remote để duyệt kho lưu trữ được kiểm duyệt)"
+        }
+        MessageId::CmdSlopDescription => "Kiểm tra hoặc xuất SlopLedger",
+        MessageId::CmdStashDescription => {
+            "Tạm cất hoặc khôi phục bản nháp (Ctrl+S để cất, /stash list/pop để xem/lấy ra)"
+        }
+        MessageId::CmdStatusDescription => "Hiển thị trạng thái thời gian chạy của phiên",
+        MessageId::CmdStatuslineDescription => {
+            "Cấu hình các mục hiển thị ở thanh trạng thái dưới cùng"
+        }
+        MessageId::CmdSubagentsDescription => "Liệt kê trạng thái của các sub-agent",
+        MessageId::CmdSwarmDescription => {
+            "Khởi chạy chế độ đa agent (sequential | mixture | distill | deliberate)"
+        }
+        MessageId::CmdSystemDescription => "Hiển thị prompt hệ thống hiện tại",
+        MessageId::CmdTaskDescription => "Quản lý các nhiệm vụ chạy ngầm",
+        MessageId::CmdTokensDescription => "Hiển thị lượng token đã sử dụng cho phiên",
+        MessageId::CmdTranslateDescription => {
+            "Bật/Tắt chế độ dịch đầu ra sang ngôn ngữ hệ thống hiện tại"
+        }
+        MessageId::CmdTranslateOff => {
+            "Đã tắt chế độ dịch đầu ra (hiển thị câu trả lời gốc của mô hình)"
+        }
+        MessageId::CmdTranslateOn => {
+            "Đã bật chế độ dịch đầu ra: câu trả lời của mô hình sẽ được hiển thị bằng tiếng Việt"
+        }
+        MessageId::TranslationInProgress => "Đang dịch câu trả lời của trợ lý...",
+        MessageId::TranslationComplete => "Đã dịch xong",
+        MessageId::TranslationFailed => "Dịch thất bại",
+        MessageId::CmdTrustDescription => {
+            "Quản lý quyền tin cậy không gian làm việc và danh sách trắng theo đường dẫn (`/trust add <path>`, `/trust list`, `/trust on|off`)"
+        }
+        MessageId::CmdWorkspaceDescription => {
+            "Hiển thị hoặc chuyển đổi không gian làm việc hiện tại"
+        }
+        MessageId::CmdUndoDescription => "Xóa cặp tin nhắn gần nhất",
+        MessageId::CmdVerboseDescription => {
+            "Bật/Tắt chế độ hiển thị đầy đủ quá trình suy nghĩ trực tiếp"
+        }
+        MessageId::CmdCacheAdvice => {
+            "Tỷ lệ hit/miss trên ~70% sau lượt thứ ba cho thấy tiền tố bộ nhớ đệm ổn định; \nthấp hơn mức đó trong các phiên dài cho thấy có sự biến động tiền tố cần kiểm tra (#263)."
+        }
+        MessageId::CmdCacheFootnote => {
+            "* miss được suy ra từ đầu vào − hit khi nhà cung cấp không báo cáo rõ ràng.\n"
+        }
+        MessageId::CmdCacheHeader => {
+            "Thông tin cache — {count} lượt gần nhất trong tổng số {total} lượt (mô hình: {model})\n"
+        }
+        MessageId::CmdCacheNoData => {
+            "Lịch sử bộ nhớ đệm: chưa có lượt nào được ghi nhận.\n\n\
+             DeepSeek cung cấp `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens` \
+             trên mỗi lượt API mà mô hình hỗ trợ (dòng V4). Hãy chạy một lượt \
+             và thử lại lệnh /cache."
+        }
+        MessageId::CmdCacheTotals => {
+            "Σ vào: {sum_in}   Σ hit: {sum_hit}   Σ miss: {sum_miss}   tỷ lệ hit trung bình: {avg}\n"
+        }
+        MessageId::CmdCostReport => {
+            "Chi Phí Phiên Làm Việc:\n\
+             ─────────────────────────────\n\
+             Tổng chi tiêu ước tính: {cost}\n\n\
+             Các ước tính chi phí mang tính xấp xỉ và sử dụng dữ liệu viễn trắc từ nhà cung cấp nếu có.\n\n\
+             Bảng Giá API DeepSeek:\n\
+             ─────────────────────────────\n\
+             Thông tin chi tiết về giá chưa được cấu hình trong CLI này."
+        }
+        MessageId::CmdTokensCacheBoth => "{hit} hit / {miss} miss",
+        MessageId::CmdTokensCacheHitOnly => "{hit} hit / không báo cáo miss",
+        MessageId::CmdTokensCacheMissOnly => "không báo cáo hit / {miss} miss",
+        MessageId::CmdTokensContextUnknownWindow => "~{estimated} / không rõ cửa sổ ngữ cảnh",
+        MessageId::CmdTokensContextWithWindow => "~{used} / {window} ({percent}%)",
+        MessageId::FooterAgentSingular => "1 tác nhân",
+        MessageId::FooterAgentsPlural => "{count} tác nhân",
+        MessageId::FooterPressCtrlCAgain => "Nhấn Ctrl+C một lần nữa để thoát",
+        MessageId::FooterWorking => "đang xử lý",
+        MessageId::HelpSectionActions => "Hành động",
+        MessageId::HelpSectionClipboard => "Bộ nhớ tạm",
+        MessageId::HelpSectionEditing => "Chỉnh sửa đầu vào",
+        MessageId::HelpSectionHelp => "Trợ giúp",
+        MessageId::HelpSectionModes => "Chế độ",
+        MessageId::HelpSectionNavigation => "Điều hướng",
+        MessageId::HelpSectionSessions => "Phiên",
+        MessageId::CmdTokensNotReported => "không được báo cáo",
+        MessageId::CmdTokensReport => {
+            "Lượng Token Sử Dụng:\n\
+             ─────────────────────────────\n\
+             Ngữ cảnh hoạt động:        {active}\n\
+             Đầu vào API gần nhất:       {input} (viễn trắc theo lượt; có thể đếm lặp lại tiền tố qua các vòng công cụ)\n\
+             Đầu ra API gần nhất:       {output}\n\
+             Hit/miss bộ nhớ đệm:        {cache} (chỉ dành cho viễn trắc/chi phí)\n\
+             Token tích lũy:             {total} (dữ liệu viễn trắc sử dụng của phiên)\n\
+             Chi phí phiên xấp xỉ:       {cost}\n\
+             Tin nhắn API:               {api_messages}\n\
+             Tin nhắn trò chuyện:        {chat_messages}\n\
+             Mô hình:                    {model}"
+        }
+        MessageId::KbScrollTranscript => {
+            "Cuộn bản ghi trò chuyện, điều hướng lịch sử nhập hoặc chọn tệp đính kèm"
+        }
+        MessageId::KbNavigateHistory => "Điều hướng lịch sử nhập",
+        MessageId::KbBrowseHistory => "Duyệt lịch sử cuộc trò chuyện",
+        MessageId::KbScrollTranscriptAlt => "Cuộn bản ghi trò chuyện",
+        MessageId::KbScrollPage => "Cuộn bản ghi trò chuyện theo trang",
+        MessageId::KbJumpTopBottom => "Nhảy lên đầu / xuống cuối bản ghi trò chuyện",
+        MessageId::KbJumpTopBottomEmpty => "Nhảy lên đầu / xuống cuối (khi khung nhập trống)",
+        MessageId::KbJumpToolBlocks => "Nhảy giữa các khối đầu ra của công cụ",
+        MessageId::KbMoveCursor => "Di chuyển con trỏ trong khung soạn thảo",
+        MessageId::KbJumpLineStartEnd => "Nhảy về đầu / cuối dòng",
+        MessageId::KbDeleteChar => "Xóa ký tự trước / sau con trỏ, hoặc xóa tệp đính kèm đã chọn",
+        MessageId::KbClearDraft => "Xóa bản nháp hiện tại",
+        MessageId::KbStashDraft => "Tạm cất bản nháp hiện tại (dùng `/stash pop` để khôi phục)",
+        MessageId::KbSearchHistory => "Tìm kiếm lịch sử câu lệnh và khôi phục các bản nháp cục bộ",
+        MessageId::KbInsertNewline => "Chèn một dòng mới trong khung soạn thảo",
+        MessageId::KbSendDraft => "Gửi bản nháp hiện tại",
+        MessageId::KbCloseMenu => "Đóng menu, hủy yêu cầu, hủy bản nháp hoặc xóa sạch đầu vào",
+        MessageId::KbCancelOrExit => "Hủy yêu cầu, hoặc thoát khi rảnh",
+        MessageId::KbShellControls => "Mở các điều khiển shell cho một lệnh đang chạy ở tiền cảnh",
+        MessageId::KbExitEmpty => "Thoát khi khung nhập trống",
+        MessageId::KbCommandPalette => "Mở bảng lệnh (command palette)",
+        MessageId::KbFuzzyFilePicker => {
+            "Mở trình tìm file nhanh (fuzzy) (chèn @path khi nhấn Enter)"
+        }
+        MessageId::KbCompactInspector => "Mở trình kiểm tra ngữ cảnh phiên thu gọn",
+        MessageId::KbLastMessagePager => {
+            "Mở trang xem cho tin nhắn cuối cùng (khi khung nhập trống)"
+        }
+        MessageId::KbSelectedDetails => {
+            "Mở chi tiết cho công cụ hoặc tin nhắn được chọn (khi khung nhập trống)"
+        }
+        MessageId::KbToolDetailsPager => "Mở trang xem chi tiết công cụ",
+        MessageId::KbThinkingPager => "Mở Chi Tiết Hoạt Động (Activity Detail)",
+        MessageId::KbLiveTranscript => "Mở lớp phủ bản ghi trực tiếp (tự động cuộn theo đuôi)",
+        MessageId::KbBacktrackMessage => {
+            "Quay lại tin nhắn trước đó của người dùng (nhấn Trái/Phải để chuyển bước, Enter để lùi lại)"
+        }
+        MessageId::KbCompleteCycleModes => {
+            "Hoàn thành /command, xếp hàng theo dõi lượt đang chạy, chuyển đổi chế độ; Shift+Tab để chuyển đổi mức độ suy luận"
+        }
+        MessageId::KbJumpPlanAgentYolo => "Nhảy trực tiếp sang chế độ Plan / Agent / YOLO",
+        MessageId::KbAltJumpPlanAgentYolo => {
+            "Phím tắt thay thế để nhảy sang chế độ Plan / Agent / YOLO"
+        }
+        MessageId::KbFocusSidebar => {
+            "Focus vào thanh bên Work / Tasks / Agents / Context / Auto; Ctrl+Alt+0 để ẩn"
+        }
+        MessageId::KbTogglePlanAgent => "Chuyển đổi giữa chế độ Plan và Agent",
+        MessageId::KbSessionPicker => "Mở bảng chọn phiên làm việc",
+        MessageId::KbPasteAttach => "Dán văn bản hoặc đính kèm hình ảnh từ bộ nhớ tạm",
+        MessageId::KbCopySelection => "Sao chép vùng chọn hiện tại (Cmd+C trên macOS)",
+        MessageId::KbContextMenu => {
+            "Mở các hành động ngữ cảnh cho dán, vùng chọn, chi tiết tin nhắn, ngữ cảnh và trợ giúp"
+        }
+        MessageId::KbAttachPath => "Thêm một tệp văn bản cục bộ hoặc thư mục vào ngữ cảnh",
+        MessageId::KbHelpOverlay => "Mở lớp phủ trợ giúp này (khi khung nhập trống)",
+        MessageId::KbToggleHelp => "Bật/Tắt lớp phủ trợ giúp",
+        MessageId::KbToggleHelpSlash => "Bật/Tắt lớp phủ trợ giúp",
+        MessageId::HelpUsageLabel => "Sử dụng:",
+        MessageId::HelpAliasesLabel => "Bí danh:",
+        MessageId::SettingsTitle => "Cài đặt:",
+        MessageId::SettingsConfigFile => "Tệp cấu hình:",
+        MessageId::ClearConversation => "Đã xóa cuộc trò chuyện",
+        MessageId::ClearConversationBusy => {
+            "Đã xóa cuộc trò chuyện (trạng thái plan đang bận; chạy lại /clear nếu cần)"
+        }
+        MessageId::ModelChanged => "Đã thay đổi mô hình: {old} \u{2192} {new}",
+        MessageId::LinksTitle => "Liên kết DeepSeek:",
+        MessageId::LinksDashboard => "Bảng điều khiển:",
+        MessageId::LinksDocs => "Tài liệu:",
+        MessageId::LinksTip => "Mẹo: Mã khóa API có sẵn trong bảng điều khiển console.",
+        MessageId::SubagentsFetching => "Đang lấy trạng thái của các sub-agent...",
+        MessageId::HelpUnknownCommand => "Lệnh không xác định: {topic}",
+        MessageId::HomeDashboardTitle => "Bảng Điều Khiển Trang Chủ codewhale",
+        MessageId::HomeModel => "Mô hình:",
+        MessageId::HomeMode => "Chế độ:",
+        MessageId::HomeWorkspace => "Không gian làm việc:",
+        MessageId::HomeHistory => "Lịch sử:",
+        MessageId::HomeTokens => "Token:",
+        MessageId::HomeQueued => "Trong hàng đợi:",
+        MessageId::HomeSubagents => "Sub-agent:",
+        MessageId::HomeSkill => "Kỹ năng:",
+        MessageId::HomeQuickActions => "Hành động nhanh",
+        MessageId::HomeQuickLinks => "/links      - Các liên kết đến Dashboard & API",
+        MessageId::HomeQuickSkills => "/skills     - Liệt kê các kỹ năng khả dụng",
+        MessageId::HomeQuickConfig => "/config     - Mở trình chỉnh sửa cấu hình tương tác",
+        MessageId::HomeQuickSettings => "/settings    - Hiển thị các cài đặt liên tục",
+        MessageId::HomeQuickModel => "/model       - Xem hoặc chuyển đổi mô hình",
+        MessageId::HomeQuickSubagents => "/subagents   - Liệt kê trạng thái sub-agent",
+        MessageId::HomeQuickTaskList => "/task list   - Hiển thị hàng đợi nhiệm vụ ngầm",
+        MessageId::HomeQuickHelp => "/help        - Hiển thị trợ giúp",
+        MessageId::HomeModeTips => "Mẹo về Chế độ",
+        MessageId::HomeAgentModeTip => "Chế độ Agent - Sử dụng công cụ cho các nhiệm vụ tự chủ",
+        MessageId::HomeAgentModeReviewTip => {
+            "  Sử dụng Ctrl+X để xem xét ở chế độ Plan trước khi thực thi"
+        }
+        MessageId::HomeAgentModeYoloTip => "  Nhập /mode yolo để bật toàn quyền truy cập công cụ",
+        MessageId::HomeYoloModeTip => {
+            "Chế độ YOLO - Toàn quyền truy cập công cụ, không cần phê duyệt"
+        }
+        MessageId::HomeYoloModeCaution => "  Hãy cẩn thận với các thao tác mang tính phá hủy!",
+        MessageId::HomePlanModeTip => "Chế độ Plan - Thiết kế trước khi triển khai",
+        MessageId::HomePlanModeChecklistTip => {
+            "  Sử dụng /mode plan để tạo danh sách kiểm tra có cấu trúc"
+        }
+        MessageId::HomeGoalModeTip => {
+            "Theo dõi mục tiêu - Dùng /goal <mục_tiêu> để đặt mục tiêu làm việc"
+        }
+        // Onboarding — language picker.
+        MessageId::OnboardLanguageTitle => "Chọn ngôn ngữ của bạn",
+        MessageId::OnboardLanguageBlurb => {
+            "Chọn ngôn ngữ hiển thị. Bạn có thể thay đổi bất kỳ lúc nào bằng lệnh `/settings set locale <tag>`."
+        }
+        MessageId::OnboardLanguageFooter => {
+            "Nhấn phím từ 1-7 để chọn, hoặc Enter để giữ cài đặt hiện tại"
+        }
+        // Onboarding — API key entry.
+        MessageId::OnboardApiKeyTitle => "Kết nối khóa API DeepSeek của bạn",
+        MessageId::OnboardApiKeyStep1 => {
+            "Bước 1. Truy cập https://platform.deepseek.com/api_keys và tạo một khóa."
+        }
+        MessageId::OnboardApiKeyStep2 => "Bước 2. Dán khóa vào bên dưới và nhấn Enter.",
+        MessageId::OnboardApiKeySavedHint => {
+            "Được lưu vào ~/.codewhale/config.toml để có thể hoạt động từ mọi thư mục."
+        }
+        MessageId::OnboardApiKeyFormatHint => {
+            "Dán chính xác toàn bộ khóa (không chứa khoảng trắng hoặc xuống dòng)."
+        }
+        MessageId::OnboardApiKeyPlaceholder => "(dán khóa vào đây)",
+        MessageId::OnboardApiKeyLabel => "Khóa: ",
+        MessageId::OnboardApiKeyFooter => "Nhấn Enter để lưu, Esc để quay lại.",
+        // Onboarding — workspace trust.
+        MessageId::OnboardTrustTitle => "Tin cậy không gian làm việc",
+        MessageId::OnboardTrustQuestion => "Bạn có tin cậy nội dung của thư mục này không?",
+        MessageId::OnboardTrustLocationPrefix => "Bạn đang ở ",
+        MessageId::OnboardTrustRiskHint => {
+            "Làm việc với các nội dung không tin cậy sẽ tăng nguy cơ bị tấn công prompt injection."
+        }
+        MessageId::OnboardTrustEffectHint => {
+            "Tin cậy thư mục này sẽ lưu lại vào cấu hình toàn cục và bật chế độ không gian làm việc tin cậy."
+        }
+        MessageId::OnboardTrustFooterPrefix => "Nhấn ",
+        MessageId::OnboardTrustFooterMiddle => " để tin cậy và tiếp tục, ",
+        MessageId::OnboardTrustFooterSuffix => " để thoát",
+        // Onboarding — final tips.
+        MessageId::OnboardTipsTitle => "Bắt đầu đơn giản",
+        MessageId::OnboardTipsLine1 => {
+            "Viết nhiệm vụ bằng ngôn ngữ tự nhiên. Sử dụng /help hoặc Ctrl+K khi bạn muốn dùng lệnh."
+        }
+        MessageId::OnboardTipsLine2 => {
+            "Khung nhập văn bản bên dưới hỗ trợ viết nhiều dòng: Enter để gửi, Alt+Enter hoặc Ctrl+J để xuống dòng."
+        }
+        MessageId::OnboardTipsLine3 => {
+            "Chỉ chuyển đổi chế độ khi tính chất công việc thay đổi: Plan để lập kế hoạch trước khi làm, Agent để tự động thực hiện, YOLO khi bạn muốn tự động phê duyệt."
+        }
+        MessageId::OnboardTipsLine4 => {
+            "Ctrl+R để khôi phục lại các phiên làm việc trước đó, và Esc để thoát khỏi bản nháp hoặc lớp phủ hiện tại."
+        }
+        MessageId::OnboardTipsFooterEnter => "Nhấn Enter",
+        MessageId::OnboardTipsFooterAction => " để mở không gian làm việc",
+        // Context menu.
+        MessageId::CtxMenuTitle => " Nhấp chuột phải ",
+        MessageId::CtxMenuCopySelection => "Sao chép vùng chọn",
+        MessageId::CtxMenuCopySelectionDesc => "ghi văn bản transcript đã chọn",
+        MessageId::CtxMenuOpenSelection => "Mở vùng chọn",
+        MessageId::CtxMenuOpenSelectionDesc => "hiển thị văn bản đã chọn trong trình xem",
+        MessageId::CtxMenuClearSelection => "Xóa vùng chọn",
+        MessageId::CtxMenuOpenDetails => "Mở chi tiết",
+        MessageId::CtxMenuCopyMessage => "Sao chép tin nhắn",
+        MessageId::CtxMenuCopyMessageDesc => "ghi ô transcript đã bấm",
+        MessageId::CtxMenuOpenInEditor => "Mở trong trình soạn thảo",
+        MessageId::CtxMenuOpenInEditorDesc => "mở file:line trong $EDITOR",
+        MessageId::CtxMenuShowCell => "Hiển thị ô",
+        MessageId::CtxMenuShowCellDesc => "hiển thị lại ô transcript này",
+        MessageId::CtxMenuHideCell => "Ẩn ô",
+        MessageId::CtxMenuHideCellDesc => "thu gọn ô transcript này",
+        MessageId::CtxMenuShowHidden => "Hiển thị mục ẩn",
+        MessageId::CtxMenuShowHiddenDesc => "hiển thị lại tất cả ô đã thu gọn",
+        MessageId::CtxMenuPaste => "Dán",
+        MessageId::CtxMenuPasteDesc => "chèn clipboard vào khung nhập",
+        MessageId::CtxMenuCmdPalette => "Bảng lệnh",
+        MessageId::CtxMenuCmdPaletteDesc => "lệnh, kỹ năng và công cụ",
+        MessageId::CtxMenuContextInspector => "Trình kiểm tra ngữ cảnh",
+        MessageId::CtxMenuContextInspectorDesc => "ngữ cảnh đang hoạt động và gợi ý bộ nhớ đệm",
+        MessageId::CtxMenuHelp => "Trợ giúp",
+        MessageId::CtxMenuHelpDesc => "phím tắt và lệnh",
+    })
+}
+
 fn traditional_chinese(id: MessageId) -> Option<&'static str> {
     Some(match id {
         MessageId::CmdRelayDescription => "為新執行緒建立會話接力摘要",
@@ -1302,6 +1826,9 @@ fn japanese(id: MessageId) -> Option<&'static str> {
         MessageId::CmdCompactDescription => {
             "コンテキスト圧縮で容量を確保（旧式：v0.6.6 以降はサイクル再起動を推奨）"
         }
+        MessageId::CmdPurgeDescription => {
+            "エージェントに会話履歴を分析させ、不要なメッセージを削除・要約"
+        }
         MessageId::CmdConfigDescription => "インタラクティブな設定エディタを開く",
         MessageId::CmdContextDescription => "コンパクトなセッションコンテキスト検査ツールを開く",
         MessageId::CmdCostDescription => "セッションのコスト内訳を表示",
@@ -1343,7 +1870,7 @@ fn japanese(id: MessageId) -> Option<&'static str> {
             "テーマを切り替え（ダーク/ライト/グレースケール/システム）"
         }
         MessageId::CmdProviderDescription => {
-            "現在の LLM バックエンドを切り替え・確認（codewhale | nvidia-nim | ollama）"
+            "現在の LLM バックエンドを切り替え・確認（deepseek | nvidia-nim | ollama）"
         }
         MessageId::CmdQueueDescription => "キューされたメッセージを確認・編集",
         MessageId::CmdRecallDescription => {
@@ -1359,6 +1886,7 @@ fn japanese(id: MessageId) -> Option<&'static str> {
         MessageId::CmdRlmDescription => "永続 RLM コンテキストを開く: /rlm [0-3] <file_or_text>",
         MessageId::CmdSaveDescription => "セッションをファイルに保存",
         MessageId::CmdForkDescription => "現在の会話を兄弟セッションに fork",
+        MessageId::CmdNewDescription => "新しい保存済みセッションを開始",
         MessageId::CmdSessionsDescription => "セッション履歴ピッカーを開く",
         MessageId::CmdSettingsDescription => "永続化された設定を表示",
         MessageId::CmdSkillDescription => {
@@ -1367,6 +1895,7 @@ fn japanese(id: MessageId) -> Option<&'static str> {
         MessageId::CmdSkillsDescription => {
             "ローカルスキルを一覧表示（`/skills <prefix>` で絞り込み、--remote で精選レジストリを参照）"
         }
+        MessageId::CmdSlopDescription => "Inspect or export the SlopLedger",
         MessageId::CmdStashDescription => {
             "コンポーザーの下書きを退避／復元（Ctrl+S で退避、/stash list|pop）"
         }
@@ -1557,7 +2086,7 @@ fn japanese(id: MessageId) -> Option<&'static str> {
         MessageId::OnboardLanguageBlurb => {
             "UI 言語を選んでください。`/settings set locale <tag>` でいつでも変更できます。"
         }
-        MessageId::OnboardLanguageFooter => "1〜6 で選択、または Enter で現在の設定を維持",
+        MessageId::OnboardLanguageFooter => "1〜7 で選択、または Enter で現在の設定を維持",
         // Onboarding — API key entry.
         MessageId::OnboardApiKeyTitle => "DeepSeek API キーを設定",
         MessageId::OnboardApiKeyStep1 => {
@@ -1602,6 +2131,32 @@ fn japanese(id: MessageId) -> Option<&'static str> {
         }
         MessageId::OnboardTipsFooterEnter => "Enter を押す",
         MessageId::OnboardTipsFooterAction => " とワークスペースが開きます",
+        // Context menu.
+        MessageId::CtxMenuTitle => " 右クリック ",
+        MessageId::CtxMenuCopySelection => "選択をコピー",
+        MessageId::CtxMenuCopySelectionDesc => "選択したトランスクリプトのテキストを書き込む",
+        MessageId::CtxMenuOpenSelection => "選択を開く",
+        MessageId::CtxMenuOpenSelectionDesc => "選択したテキストをページャで表示",
+        MessageId::CtxMenuClearSelection => "選択を解除",
+        MessageId::CtxMenuOpenDetails => "詳細を開く",
+        MessageId::CtxMenuCopyMessage => "メッセージをコピー",
+        MessageId::CtxMenuCopyMessageDesc => "クリックしたトランスクリプトセルを書き込む",
+        MessageId::CtxMenuOpenInEditor => "エディタで開く",
+        MessageId::CtxMenuOpenInEditorDesc => "$EDITOR で file:line を開く",
+        MessageId::CtxMenuShowCell => "セルを表示",
+        MessageId::CtxMenuShowCellDesc => "このトランスクリプトセルを再表示",
+        MessageId::CtxMenuHideCell => "セルを隠す",
+        MessageId::CtxMenuHideCellDesc => "このトランスクリプトセルを折りたたむ",
+        MessageId::CtxMenuShowHidden => "非表示を表示",
+        MessageId::CtxMenuShowHiddenDesc => "すべての折りたたまれたセルを再表示",
+        MessageId::CtxMenuPaste => "貼り付け",
+        MessageId::CtxMenuPasteDesc => "クリップボードをコンポーザに挿入",
+        MessageId::CtxMenuCmdPalette => "コマンドパレット",
+        MessageId::CtxMenuCmdPaletteDesc => "コマンド、スキル、ツール",
+        MessageId::CtxMenuContextInspector => "コンテキストインスペクタ",
+        MessageId::CtxMenuContextInspectorDesc => "アクティブなコンテキストとキャッシュヒント",
+        MessageId::CtxMenuHelp => "ヘルプ",
+        MessageId::CtxMenuHelpDesc => "キー操作とコマンド",
     })
 }
 
@@ -1657,6 +2212,7 @@ fn chinese_simplified(id: MessageId) -> Option<&'static str> {
         MessageId::CmdCompactDescription => {
             "触发上下文压缩以释放空间（旧版命令；v0.6.6 起建议改用循环重启）"
         }
+        MessageId::CmdPurgeDescription => "让 Agent 分析对话历史，精确保留有用信息并移除冗余内容",
         MessageId::CmdConfigDescription => "打开交互式配置编辑器",
         MessageId::CmdContextDescription => "打开紧凑会话上下文检查器",
         MessageId::CmdCostDescription => "显示本次会话的费用明细",
@@ -1688,7 +2244,7 @@ fn chinese_simplified(id: MessageId) -> Option<&'static str> {
         MessageId::CmdNoteDescription => "添加、列出、编辑或删除工作区笔记",
         MessageId::CmdThemeDescription => "切换主题：深色、浅色、灰度或系统",
         MessageId::CmdProviderDescription => {
-            "切换或查看当前 LLM 后端（codewhale | nvidia-nim | ollama）"
+            "切换或查看当前 LLM 后端（deepseek | nvidia-nim | ollama）"
         }
         MessageId::CmdQueueDescription => "查看或编辑已排队的消息",
         MessageId::CmdRecallDescription => "搜索此前的循环归档（基于消息文本的 BM25 检索）",
@@ -1702,12 +2258,14 @@ fn chinese_simplified(id: MessageId) -> Option<&'static str> {
         MessageId::CmdRlmDescription => "打开持久 RLM 上下文：/rlm [0-3] <file_or_text>",
         MessageId::CmdSaveDescription => "将会话保存到文件",
         MessageId::CmdForkDescription => "将当前对话分叉为兄弟会话",
+        MessageId::CmdNewDescription => "开始一个新的已保存会话",
         MessageId::CmdSessionsDescription => "打开会话历史选择器",
         MessageId::CmdSettingsDescription => "显示持久化设置",
         MessageId::CmdSkillDescription => "激活技能，或安装/更新/卸载/信任社区技能",
         MessageId::CmdSkillsDescription => {
             "列出本地技能（用 `/skills <prefix>` 按名称前缀过滤，--remote 浏览精选注册表）"
         }
+        MessageId::CmdSlopDescription => "Inspect or export the SlopLedger",
         MessageId::CmdStashDescription => "暂存或恢复输入草稿（Ctrl+S 暂存，/stash list|pop）",
         MessageId::CmdStatusDescription => "显示当前运行状态",
         MessageId::CmdStatuslineDescription => "配置底栏要显示哪些条目",
@@ -1874,7 +2432,7 @@ fn chinese_simplified(id: MessageId) -> Option<&'static str> {
         MessageId::OnboardLanguageBlurb => {
             "选择界面语言。可随时使用 `/settings set locale <tag>` 修改。"
         }
-        MessageId::OnboardLanguageFooter => "按 1-6 选择，或按 Enter 保留当前设置",
+        MessageId::OnboardLanguageFooter => "按 1-7 选择，或按 Enter 保留当前设置",
         // Onboarding — API key entry.
         MessageId::OnboardApiKeyTitle => "连接你的 DeepSeek API 密钥",
         MessageId::OnboardApiKeyStep1 => {
@@ -1909,6 +2467,32 @@ fn chinese_simplified(id: MessageId) -> Option<&'static str> {
         MessageId::OnboardTipsLine4 => "Ctrl+R 恢复历史会话，Esc 退出当前输入或弹层。",
         MessageId::OnboardTipsFooterEnter => "按 Enter",
         MessageId::OnboardTipsFooterAction => " 进入工作区",
+        // Context menu.
+        MessageId::CtxMenuTitle => " 右键菜单 ",
+        MessageId::CtxMenuCopySelection => "复制所选",
+        MessageId::CtxMenuCopySelectionDesc => "将选中的记录区域文本写入剪贴板",
+        MessageId::CtxMenuOpenSelection => "打开所选",
+        MessageId::CtxMenuOpenSelectionDesc => "在翻阅器中查看选中文本",
+        MessageId::CtxMenuClearSelection => "清除选择",
+        MessageId::CtxMenuOpenDetails => "打开详情",
+        MessageId::CtxMenuCopyMessage => "复制消息",
+        MessageId::CtxMenuCopyMessageDesc => "将点击的记录条目写入剪贴板",
+        MessageId::CtxMenuOpenInEditor => "在编辑器中打开",
+        MessageId::CtxMenuOpenInEditorDesc => "在 $EDITOR 中打开 file:line",
+        MessageId::CtxMenuShowCell => "显示条目",
+        MessageId::CtxMenuShowCellDesc => "取消隐藏此记录条目",
+        MessageId::CtxMenuHideCell => "隐藏条目",
+        MessageId::CtxMenuHideCellDesc => "折叠此记录条目",
+        MessageId::CtxMenuShowHidden => "显示已隐藏",
+        MessageId::CtxMenuShowHiddenDesc => "取消隐藏所有已折叠条目",
+        MessageId::CtxMenuPaste => "粘贴",
+        MessageId::CtxMenuPasteDesc => "将剪贴板插入输入框",
+        MessageId::CtxMenuCmdPalette => "命令面板",
+        MessageId::CtxMenuCmdPaletteDesc => "命令、技能和工具",
+        MessageId::CtxMenuContextInspector => "上下文检查器",
+        MessageId::CtxMenuContextInspectorDesc => "活动上下文和缓存提示",
+        MessageId::CtxMenuHelp => "帮助",
+        MessageId::CtxMenuHelpDesc => "快捷键和命令",
     })
 }
 
@@ -1972,6 +2556,9 @@ fn portuguese_brazil(id: MessageId) -> Option<&'static str> {
         MessageId::CmdCompactDescription => {
             "Compactar o contexto para liberar espaço (legado; a v0.6.6 prefere o reinício de ciclo)"
         }
+        MessageId::CmdPurgeDescription => {
+            "Deixe o agente podar cirurgicamente o histórico para liberar espaço de contexto"
+        }
         MessageId::CmdConfigDescription => "Abrir o editor interativo de configuração",
         MessageId::CmdContextDescription => "Abrir o inspetor compacto de contexto da sessão",
         MessageId::CmdCostDescription => "Exibir o detalhamento de custo da sessão",
@@ -2017,7 +2604,7 @@ fn portuguese_brazil(id: MessageId) -> Option<&'static str> {
         MessageId::CmdNoteDescription => "Adicionar, listar, editar ou remover notas do workspace",
         MessageId::CmdThemeDescription => "Alternar tema: escuro, claro, tons de cinza ou sistema",
         MessageId::CmdProviderDescription => {
-            "Trocar ou exibir o backend LLM ativo (codewhale | nvidia-nim | ollama)"
+            "Trocar ou exibir o backend LLM ativo (deepseek | nvidia-nim | ollama)"
         }
         MessageId::CmdQueueDescription => "Ver ou editar mensagens enfileiradas",
         MessageId::CmdRecallDescription => {
@@ -2037,6 +2624,7 @@ fn portuguese_brazil(id: MessageId) -> Option<&'static str> {
         }
         MessageId::CmdSaveDescription => "Salvar a sessão em arquivo",
         MessageId::CmdForkDescription => "Bifurcar a conversa ativa para uma sessão irmã",
+        MessageId::CmdNewDescription => "Iniciar uma nova sessão salva",
         MessageId::CmdSessionsDescription => "Abrir seletor de histórico de sessões",
         MessageId::CmdSettingsDescription => "Exibir as configurações persistidas",
         MessageId::CmdSkillDescription => {
@@ -2045,6 +2633,7 @@ fn portuguese_brazil(id: MessageId) -> Option<&'static str> {
         MessageId::CmdSkillsDescription => {
             "Listar skills locais (filtre com `/skills <prefixo>`; --remote navega pelo registro curado)"
         }
+        MessageId::CmdSlopDescription => "Inspect or export the SlopLedger",
         MessageId::CmdStashDescription => {
             "Estacionar ou restaurar rascunho do compositor (Ctrl+S estaciona, /stash list|pop)"
         }
@@ -2250,7 +2839,7 @@ fn portuguese_brazil(id: MessageId) -> Option<&'static str> {
             "Escolha o idioma da interface. Você pode mudá-lo a qualquer momento com `/settings set locale <tag>`."
         }
         MessageId::OnboardLanguageFooter => {
-            "Pressione 1-6 para escolher, ou Enter para manter a configuração atual"
+            "Pressione 1-7 para escolher, ou Enter para manter a configuração atual"
         }
         // Onboarding — API key entry.
         MessageId::OnboardApiKeyTitle => "Conecte sua chave de API DeepSeek",
@@ -2296,6 +2885,32 @@ fn portuguese_brazil(id: MessageId) -> Option<&'static str> {
         }
         MessageId::OnboardTipsFooterEnter => "Pressione Enter",
         MessageId::OnboardTipsFooterAction => " para abrir o workspace",
+        // Context menu.
+        MessageId::CtxMenuTitle => " Clique direito ",
+        MessageId::CtxMenuCopySelection => "Copiar seleção",
+        MessageId::CtxMenuCopySelectionDesc => "copiar texto selecionado da transcrição",
+        MessageId::CtxMenuOpenSelection => "Abrir seleção",
+        MessageId::CtxMenuOpenSelectionDesc => "mostrar texto selecionado no visualizador",
+        MessageId::CtxMenuClearSelection => "Limpar seleção",
+        MessageId::CtxMenuOpenDetails => "Abrir detalhes",
+        MessageId::CtxMenuCopyMessage => "Copiar mensagem",
+        MessageId::CtxMenuCopyMessageDesc => "copiar célula da transcrição clicada",
+        MessageId::CtxMenuOpenInEditor => "Abrir no editor",
+        MessageId::CtxMenuOpenInEditorDesc => "abrir file:line no $EDITOR",
+        MessageId::CtxMenuShowCell => "Mostrar célula",
+        MessageId::CtxMenuShowCellDesc => "reexibir esta célula da transcrição",
+        MessageId::CtxMenuHideCell => "Ocultar célula",
+        MessageId::CtxMenuHideCellDesc => "recolher esta célula da transcrição",
+        MessageId::CtxMenuShowHidden => "Mostrar ocultas",
+        MessageId::CtxMenuShowHiddenDesc => "reexibir todas as células recolhidas",
+        MessageId::CtxMenuPaste => "Colar",
+        MessageId::CtxMenuPasteDesc => "inserir área de transferência no compositor",
+        MessageId::CtxMenuCmdPalette => "Paleta de comandos",
+        MessageId::CtxMenuCmdPaletteDesc => "comandos, habilidades e ferramentas",
+        MessageId::CtxMenuContextInspector => "Inspetor de contexto",
+        MessageId::CtxMenuContextInspectorDesc => "contexto ativo e dicas de cache",
+        MessageId::CtxMenuHelp => "Ajuda",
+        MessageId::CtxMenuHelpDesc => "atalhos de teclado e comandos",
     })
 }
 
@@ -2359,6 +2974,9 @@ fn spanish_latin_america(id: MessageId) -> Option<&'static str> {
         MessageId::CmdCompactDescription => {
             "Compactar el contexto para liberar espacio (heredado; v0.6.6 prefiere reinicio de ciclo)"
         }
+        MessageId::CmdPurgeDescription => {
+            "Permite al agente eliminar quirúrgicamente historial innecesario para liberar espacio de contexto"
+        }
         MessageId::CmdConfigDescription => "Abrir el editor interactivo de configuración",
         MessageId::CmdContextDescription => "Abrir el inspector compacto de contexto de la sesión",
         MessageId::CmdCostDescription => "Mostrar el desglose de costo de la sesión",
@@ -2408,7 +3026,7 @@ fn spanish_latin_america(id: MessageId) -> Option<&'static str> {
         MessageId::CmdNoteDescription => "Agregar nota al archivo persistente (.deepseek/notes.md)",
         MessageId::CmdThemeDescription => "Alternar entre tema claro y oscuro",
         MessageId::CmdProviderDescription => {
-            "Cambiar o mostrar el backend LLM activo (codewhale | nvidia-nim | ollama)"
+            "Cambiar o mostrar el backend LLM activo (deepseek | nvidia-nim | ollama)"
         }
         MessageId::CmdQueueDescription => "Ver o editar mensajes en cola",
         MessageId::CmdRecallDescription => {
@@ -2428,6 +3046,7 @@ fn spanish_latin_america(id: MessageId) -> Option<&'static str> {
         }
         MessageId::CmdSaveDescription => "Guardar la sesión en archivo",
         MessageId::CmdForkDescription => "Bifurcar la conversación activa a una sesión hermana",
+        MessageId::CmdNewDescription => "Iniciar una nueva sesión guardada",
         MessageId::CmdSessionsDescription => "Abrir el selector de sesiones",
         MessageId::CmdSettingsDescription => "Mostrar las configuraciones persistidas",
         MessageId::CmdSkillDescription => {
@@ -2436,6 +3055,7 @@ fn spanish_latin_america(id: MessageId) -> Option<&'static str> {
         MessageId::CmdSkillsDescription => {
             "Listar skills locales (filtra con `/skills <prefijo>`; --remote navega el registro curado)"
         }
+        MessageId::CmdSlopDescription => "Inspect or export the SlopLedger",
         MessageId::CmdStashDescription => {
             "Estacionar o restaurar borrador del compositor (Ctrl+S estaciona, /stash list|pop)"
         }
@@ -2646,7 +3266,7 @@ fn spanish_latin_america(id: MessageId) -> Option<&'static str> {
             "Elige el idioma de la interfaz. Puedes cambiarlo en cualquier momento con `/settings set locale <etiqueta>`."
         }
         MessageId::OnboardLanguageFooter => {
-            "Presiona 1-5 para elegir, o Enter para mantener la configuración actual"
+            "Presiona 1-7 para elegir, o Enter para mantener la configuración actual"
         }
         MessageId::OnboardApiKeyTitle => "Conecta tu clave de API DeepSeek",
         MessageId::OnboardApiKeyStep1 => {
@@ -2689,6 +3309,32 @@ fn spanish_latin_america(id: MessageId) -> Option<&'static str> {
         }
         MessageId::OnboardTipsFooterEnter => "Presiona Enter",
         MessageId::OnboardTipsFooterAction => " para abrir el workspace",
+        // Context menu.
+        MessageId::CtxMenuTitle => " Clic derecho ",
+        MessageId::CtxMenuCopySelection => "Copiar selección",
+        MessageId::CtxMenuCopySelectionDesc => "copiar texto seleccionado de la transcripción",
+        MessageId::CtxMenuOpenSelection => "Abrir selección",
+        MessageId::CtxMenuOpenSelectionDesc => "mostrar texto seleccionado en el visor",
+        MessageId::CtxMenuClearSelection => "Limpiar selección",
+        MessageId::CtxMenuOpenDetails => "Abrir detalles",
+        MessageId::CtxMenuCopyMessage => "Copiar mensaje",
+        MessageId::CtxMenuCopyMessageDesc => "copiar celda de transcripción seleccionada",
+        MessageId::CtxMenuOpenInEditor => "Abrir en editor",
+        MessageId::CtxMenuOpenInEditorDesc => "abrir file:line en $EDITOR",
+        MessageId::CtxMenuShowCell => "Mostrar celda",
+        MessageId::CtxMenuShowCellDesc => "volver a mostrar esta celda de transcripción",
+        MessageId::CtxMenuHideCell => "Ocultar celda",
+        MessageId::CtxMenuHideCellDesc => "colapsar esta celda de transcripción",
+        MessageId::CtxMenuShowHidden => "Mostrar ocultas",
+        MessageId::CtxMenuShowHiddenDesc => "volver a mostrar todas las celdas colapsadas",
+        MessageId::CtxMenuPaste => "Pegar",
+        MessageId::CtxMenuPasteDesc => "insertar portapapeles en el compositor",
+        MessageId::CtxMenuCmdPalette => "Paleta de comandos",
+        MessageId::CtxMenuCmdPaletteDesc => "comandos, habilidades y herramientas",
+        MessageId::CtxMenuContextInspector => "Inspector de contexto",
+        MessageId::CtxMenuContextInspectorDesc => "contexto activo y sugerencias de caché",
+        MessageId::CtxMenuHelp => "Ayuda",
+        MessageId::CtxMenuHelpDesc => "atajos de teclado y comandos",
     })
 }
 
@@ -2763,6 +3409,23 @@ mod tests {
         );
     }
 
+    #[test]
+    fn provider_description_names_deepseek_backend() {
+        for locale in Locale::shipped() {
+            let description = tr(*locale, MessageId::CmdProviderDescription);
+            assert!(
+                description.contains("deepseek"),
+                "{} provider description should mention deepseek: {description}",
+                locale.tag()
+            );
+            assert!(
+                !description.contains("codewhale |"),
+                "{} provider description should not name codewhale as a backend: {description}",
+                locale.tag()
+            );
+        }
+    }
+
     #[test]
     fn width_truncation_handles_cjk_rtl_indic_and_latin_samples() {
         let samples = [
diff --git a/crates/tui/src/logging.rs b/crates/tui/src/logging.rs
index 1dd8e330..1e47d512 100644
--- a/crates/tui/src/logging.rs
+++ b/crates/tui/src/logging.rs
@@ -6,12 +6,27 @@ use colored::Colorize;
 
 use crate::palette;
 static VERBOSE: AtomicBool = AtomicBool::new(false);
+#[cfg(windows)]
+static VERBOSE_SNAPSHOT: AtomicBool = AtomicBool::new(false);
 
 /// Enable or disable verbose logging output.
 pub fn set_verbose(enabled: bool) {
     VERBOSE.store(enabled, Ordering::SeqCst);
 }
 
+/// Capture the current verbose state so the TUI can restore it after
+/// temporarily suppressing Windows alt-screen output.
+#[cfg(windows)]
+pub fn snapshot_verbose_state() {
+    VERBOSE_SNAPSHOT.store(is_verbose(), Ordering::SeqCst);
+}
+
+/// Restore the last captured verbose state.
+#[cfg(windows)]
+pub fn restore_verbose_state() {
+    set_verbose(VERBOSE_SNAPSHOT.load(Ordering::SeqCst));
+}
+
 /// Return true when `DEEPSEEK_LOG_LEVEL` requests verbose output.
 ///
 /// Note: `RUST_LOG` is intentionally NOT checked here — it controls the
@@ -61,8 +76,12 @@ pub fn warn(message: impl AsRef<str>) {
 }
 
 #[cfg(test)]
+#[cfg(windows)]
 mod tests {
     use super::*;
+    use std::sync::Mutex;
+
+    static TEST_GUARD: Mutex<()> = Mutex::new(());
 
     #[test]
     fn log_value_parser_accepts_common_rust_log_directives() {
@@ -74,4 +93,40 @@ mod tests {
         assert!(!log_value_enables_verbose("warn"));
         assert!(!log_value_enables_verbose("codewhale_tui=off"));
     }
+
+    #[test]
+    fn snapshot_and_restore_verbose_state_round_trip() {
+        let _guard = TEST_GUARD.lock().unwrap_or_else(|err| err.into_inner());
+
+        set_verbose(false);
+        snapshot_verbose_state();
+        set_verbose(true);
+        restore_verbose_state();
+        assert!(!is_verbose());
+
+        set_verbose(true);
+        snapshot_verbose_state();
+        set_verbose(false);
+        restore_verbose_state();
+        assert!(is_verbose());
+
+        set_verbose(false);
+    }
+
+    #[test]
+    fn restore_keeps_cli_verbose_state_even_when_env_is_not_verbose() {
+        let _guard = TEST_GUARD.lock().unwrap_or_else(|err| err.into_inner());
+
+        set_verbose(true);
+        snapshot_verbose_state();
+
+        // Simulate the Windows alt-screen suppression path. The restore must
+        // bring back the pre-suppression CLI state without depending on the
+        // environment.
+        set_verbose(false);
+        restore_verbose_state();
+
+        assert!(is_verbose());
+        set_verbose(false);
+    }
 }
diff --git a/crates/tui/src/lsp/registry.rs b/crates/tui/src/lsp/registry.rs
index c90834b9..34664c50 100644
--- a/crates/tui/src/lsp/registry.rs
+++ b/crates/tui/src/lsp/registry.rs
@@ -18,6 +18,8 @@ pub enum Language {
     Python,
     TypeScript,
     JavaScript,
+    Java,
+    Vue,
     C,
     Cpp,
     Other,
@@ -34,6 +36,8 @@ impl Language {
             Language::Python => "python",
             Language::TypeScript => "typescript",
             Language::JavaScript => "javascript",
+            Language::Java => "java",
+            Language::Vue => "vue",
             Language::C => "c",
             Language::Cpp => "cpp",
             Language::Other => "other",
@@ -42,7 +46,7 @@ impl Language {
 
     /// LSP `languageId` value used in `textDocument/didOpen`. We follow the
     /// LSP-spec values: `rust`, `go`, `python`, `typescript`, `javascript`,
-    /// `c`, `cpp`.
+    /// `java`, `vue`, `c`, `cpp`.
     #[must_use]
     pub fn language_id(self) -> &'static str {
         match self {
@@ -51,6 +55,8 @@ impl Language {
             Language::Python => "python",
             Language::TypeScript => "typescript",
             Language::JavaScript => "javascript",
+            Language::Java => "java",
+            Language::Vue => "vue",
             Language::C => "c",
             Language::Cpp => "cpp",
             Language::Other => "plaintext",
@@ -73,6 +79,8 @@ pub fn detect_language(path: &Path) -> Language {
         "py" | "pyi" => Language::Python,
         "ts" | "tsx" => Language::TypeScript,
         "js" | "jsx" | "mjs" | "cjs" => Language::JavaScript,
+        "java" => Language::Java,
+        "vue" => Language::Vue,
         "c" | "h" => Language::C,
         "cpp" | "cc" | "cxx" | "hpp" | "hxx" | "hh" => Language::Cpp,
         _ => Language::Other,
@@ -91,6 +99,8 @@ pub fn server_for(lang: Language) -> Option<(&'static str, &'static [&'static st
         Language::TypeScript | Language::JavaScript => {
             Some(("typescript-language-server", &["--stdio"]))
         }
+        Language::Java => Some(("jdtls", &[])),
+        Language::Vue => Some(("vue-language-server", &["--stdio"])),
         Language::C | Language::Cpp => Some(("clangd", &[])),
         Language::Other => None,
     }
@@ -132,6 +142,32 @@ mod tests {
         );
     }
 
+    #[test]
+    fn detects_java_extension() {
+        assert_eq!(detect_language(&PathBuf::from("App.java")), Language::Java);
+        assert_eq!(detect_language(&PathBuf::from("APP.JAVA")), Language::Java);
+    }
+
+    #[test]
+    fn detects_vue_extension() {
+        assert_eq!(
+            detect_language(&PathBuf::from("Component.vue")),
+            Language::Vue
+        );
+        assert_eq!(
+            detect_language(&PathBuf::from("COMPONENT.VUE")),
+            Language::Vue
+        );
+    }
+
+    #[test]
+    fn language_ids_for_java_and_vue_match_lsp_values() {
+        assert_eq!(Language::Java.as_key(), "java");
+        assert_eq!(Language::Java.language_id(), "java");
+        assert_eq!(Language::Vue.as_key(), "vue");
+        assert_eq!(Language::Vue.language_id(), "vue");
+    }
+
     #[test]
     fn server_for_rust_is_rust_analyzer() {
         let (cmd, args) = server_for(Language::Rust).expect("rust has a server");
@@ -139,6 +175,20 @@ mod tests {
         assert!(args.is_empty());
     }
 
+    #[test]
+    fn server_for_java_is_jdtls() {
+        let (cmd, args) = server_for(Language::Java).expect("java has a server");
+        assert_eq!(cmd, "jdtls");
+        assert!(args.is_empty());
+    }
+
+    #[test]
+    fn server_for_vue_is_vue_language_server() {
+        let (cmd, args) = server_for(Language::Vue).expect("vue has a server");
+        assert_eq!(cmd, "vue-language-server");
+        assert_eq!(args, &["--stdio"]);
+    }
+
     #[test]
     fn server_for_other_is_none() {
         assert!(server_for(Language::Other).is_none());
diff --git a/crates/tui/src/main.rs b/crates/tui/src/main.rs
index 34cb7fce..b339e98b 100644
--- a/crates/tui/src/main.rs
+++ b/crates/tui/src/main.rs
@@ -52,6 +52,7 @@ mod pricing;
 mod project_context;
 mod project_doc;
 mod prompts;
+mod purge;
 pub mod repl;
 mod retry_status;
 pub mod rlm;
@@ -61,22 +62,29 @@ mod runtime_threads;
 mod sandbox;
 mod schema_migration;
 mod seam_manager;
+#[allow(dead_code)]
+mod session_failure_classifier;
 mod session_manager;
 mod settings;
+mod shell_dispatcher;
 mod skill_state;
 mod skills;
+mod slop_ledger;
 mod snapshot;
 mod task_manager;
 #[cfg(test)]
 mod test_support;
+mod theme_qa_audit;
+mod tool_output_receipts;
 mod tools;
 mod tui;
 mod utils;
 mod vision;
 mod working_set;
+mod workspace_discovery;
 mod workspace_trust;
 
-use crate::config::{Config, DEFAULT_TEXT_MODEL, MAX_SUBAGENTS};
+use crate::config::{Config, DEFAULT_TEXT_MODEL, MAX_SUBAGENTS, effective_home_dir};
 use crate::eval::{EvalHarness, EvalHarnessConfig, ScenarioStepKind};
 use crate::features::{Feature, render_feature_table};
 use crate::llm_client::LlmClient;
@@ -116,7 +124,7 @@ struct Cli {
     #[command(flatten)]
     feature_toggles: FeatureToggles,
 
-    /// Send a one-shot prompt (non-interactive)
+    /// Initial prompt to submit in the interactive TUI. Use `exec` for non-interactive runs.
     #[arg(short, long, value_name = "PROMPT", num_args = 1..)]
     prompt: Vec<String>,
 
@@ -422,6 +430,10 @@ fn join_prompt_parts(parts: &[String]) -> String {
     parts.join(" ")
 }
 
+fn top_level_prompt_initial_input(parts: &[String]) -> Option<tui::InitialInput> {
+    (!parts.is_empty()).then(|| tui::InitialInput::Submit(join_prompt_parts(parts)))
+}
+
 fn resolve_exec_resume_session_id(args: &ExecArgs, workspace: &Path) -> Result<Option<String>> {
     if let Some(id) = args.resume.as_ref().or(args.session_id.as_ref()) {
         return Ok(Some(id.clone()));
@@ -568,12 +580,15 @@ struct ServeArgs {
     /// Start runtime HTTP/SSE API server
     #[arg(long)]
     http: bool,
+    /// Start runtime HTTP/SSE API server with the built-in mobile control page
+    #[arg(long)]
+    mobile: bool,
     /// Start ACP server over stdio for editor clients such as Zed
     #[arg(long)]
     acp: bool,
-    /// Bind host for HTTP server (default localhost)
-    #[arg(long, default_value = "127.0.0.1")]
-    host: String,
+    /// Bind host for HTTP server (default localhost; --mobile defaults to 0.0.0.0)
+    #[arg(long)]
+    host: Option<String>,
     /// Bind port for HTTP server
     #[arg(long, default_value_t = 7878)]
     port: u16,
@@ -595,6 +610,44 @@ struct ServeArgs {
     insecure_no_auth: bool,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ServeBindHost {
+    host: String,
+    mobile_rebound_to_lan: bool,
+}
+
+fn resolve_serve_bind_host(mobile: bool, host: Option<String>) -> ServeBindHost {
+    match (mobile, host) {
+        (true, None) => ServeBindHost {
+            host: "0.0.0.0".to_string(),
+            mobile_rebound_to_lan: true,
+        },
+        (_, Some(host)) => ServeBindHost {
+            host,
+            mobile_rebound_to_lan: false,
+        },
+        (false, None) => ServeBindHost {
+            host: "127.0.0.1".to_string(),
+            mobile_rebound_to_lan: false,
+        },
+    }
+}
+
+fn validate_serve_mode_selection(mcp: bool, http: bool, mobile: bool, acp: bool) -> Result<bool> {
+    if http && mobile {
+        bail!("--http and --mobile are mutually exclusive; choose one");
+    }
+    let http_selected = http || mobile;
+    let selected_modes = [mcp, http_selected, acp]
+        .into_iter()
+        .filter(|selected| *selected)
+        .count();
+    if selected_modes != 1 {
+        bail!("Choose exactly one server mode: --mcp, --http/--mobile, or --acp");
+    }
+    Ok(http_selected)
+}
+
 #[derive(Subcommand, Debug, Clone)]
 enum McpCommand {
     /// List configured MCP servers
@@ -627,6 +680,9 @@ enum McpCommand {
         /// URL for streamable HTTP/SSE server
         #[arg(long, conflicts_with = "command")]
         url: Option<String>,
+        /// Explicit URL transport override. Use "sse" for legacy SSE endpoints.
+        #[arg(long, requires = "url")]
+        transport: Option<String>,
         /// Arguments for command-based servers
         #[arg(long = "arg")]
         args: Vec<String>,
@@ -731,6 +787,11 @@ enum SandboxCommand {
 async fn main() -> Result<()> {
     configure_windows_console_utf8();
 
+    // ── Process hardening (#2183) ─────────────────────────────────────────
+    // MUST run before Tokio is booted and before any threads are spawned.
+    // See crates/tui/src/sandbox/process_hardening.rs for ordering rationale.
+    crate::sandbox::process_hardening::apply_process_hardening();
+
     // Set up process panic hook before anything else — writes crash dumps
     // to ~/.deepseek/crashes/ even if the panic happens before tokio is up,
     // and restores the terminal so a panicked TUI doesn't leave the user's
@@ -833,8 +894,12 @@ async fn main() -> Result<()> {
                     std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
                 });
                 let resume_session_id = resolve_exec_resume_session_id(&args, &workspace)?;
+                // The `deepseek` launcher forwards `--yolo` to this binary via
+                // the DEEPSEEK_YOLO env var (which the config loader folds into
+                // `config.yolo`), not as a CLI flag. Honour either source.
+                let yolo = cli.yolo || config.yolo.unwrap_or(false);
                 let needs_engine = args.auto
-                    || cli.yolo
+                    || yolo
                     || resume_session_id.is_some()
                     || args.output_format == ExecOutputFormat::StreamJson;
                 if needs_engine {
@@ -842,7 +907,7 @@ async fn main() -> Result<()> {
                         || config.max_subagents(),
                         |value| value.clamp(1, MAX_SUBAGENTS),
                     );
-                    let auto_mode = args.auto || cli.yolo;
+                    let auto_mode = args.auto || yolo;
                     run_exec_agent(
                         &config,
                         &model,
@@ -913,28 +978,30 @@ async fn main() -> Result<()> {
                 let workspace = cli.workspace.clone().unwrap_or_else(|| {
                     std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
                 });
-                let selected_modes = [args.mcp, args.http, args.acp]
-                    .into_iter()
-                    .filter(|selected| *selected)
-                    .count();
-                if selected_modes != 1 {
-                    bail!("Choose exactly one server mode: --mcp, --http, or --acp");
-                }
+                let http_selected =
+                    validate_serve_mode_selection(args.mcp, args.http, args.mobile, args.acp)?;
                 if args.mcp {
-                    mcp_server::run_mcp_server(workspace)
-                } else if args.http {
+                    tokio::task::block_in_place(|| mcp_server::run_mcp_server(workspace))
+                } else if http_selected {
                     let config = load_config_from_cli(&cli)?;
                     let cors_origins = resolve_cors_origins(&config, &args.cors_origin);
+                    let bind_host = resolve_serve_bind_host(args.mobile, args.host);
+                    if bind_host.mobile_rebound_to_lan {
+                        println!(
+                            "WARNING: --mobile is binding to 0.0.0.0 so LAN devices can reach the mobile control page. Use --host 127.0.0.1 to keep mobile loopback-only."
+                        );
+                    }
                     runtime_api::run_http_server(
                         config,
                         workspace,
                         runtime_api::RuntimeApiOptions {
-                            host: args.host,
+                            host: bind_host.host,
                             port: args.port,
                             workers: args.workers.clamp(1, 8),
                             cors_origins,
                             auth_token: args.auth_token,
                             insecure_no_auth: args.insecure_no_auth,
+                            mobile: args.mobile,
                         },
                     )
                     .await
@@ -961,12 +1028,12 @@ async fn main() -> Result<()> {
         };
     }
 
-    // One-shot prompt mode
+    // Top-level prompt mode: submit the initial prompt, then keep the TUI alive
+    // for follow-up messages. Use `codewhale exec` for explicit non-interactive
+    // one-shot behavior (#2370).
     let config = load_config_from_cli(&cli)?;
-    if !cli.prompt.is_empty() {
-        let prompt = join_prompt_parts(&cli.prompt);
-        let model = config.default_model();
-        return run_one_shot(&config, &model, &prompt).await;
+    if let Some(initial_input) = top_level_prompt_initial_input(&cli.prompt) {
+        return run_interactive(&cli, &config, None, Some(initial_input)).await;
     }
 
     // Handle session resume. Plain `codewhale` starts fresh: interrupted
@@ -1404,6 +1471,7 @@ fn mcp_template_json() -> Result<String> {
             args: vec!["./path/to/your-mcp-server.js".to_string()],
             env: std::collections::HashMap::new(),
             url: None,
+            transport: None,
             connect_timeout: None,
             execute_timeout: None,
             read_timeout: None,
@@ -1853,6 +1921,10 @@ fn run_setup_status(config: &Config, workspace: &Path) -> Result<()> {
                     "OPENROUTER_API_KEY",
                     "codewhale auth set --provider openrouter --api-key \"...\"",
                 ),
+                crate::config::ApiProvider::XiaomiMimo => (
+                    "XIAOMI_MIMO_API_KEY/MIMO_API_KEY",
+                    "codewhale auth set --provider xiaomi-mimo --api-key \"...\"",
+                ),
                 crate::config::ApiProvider::Novita => (
                     "NOVITA_API_KEY",
                     "codewhale auth set --provider novita --api-key \"...\"",
@@ -1861,6 +1933,10 @@ fn run_setup_status(config: &Config, workspace: &Path) -> Result<()> {
                     "FIREWORKS_API_KEY",
                     "codewhale auth set --provider fireworks --api-key \"...\"",
                 ),
+                crate::config::ApiProvider::Moonshot => (
+                    "MOONSHOT_API_KEY/KIMI_API_KEY",
+                    "codewhale auth set --provider moonshot --api-key \"...\"",
+                ),
                 crate::config::ApiProvider::Sglang => (
                     "SGLANG_API_KEY",
                     "codewhale auth set --provider sglang --api-key \"...\"",
@@ -1872,6 +1948,10 @@ fn run_setup_status(config: &Config, workspace: &Path) -> Result<()> {
                 crate::config::ApiProvider::Ollama => {
                     ("OLLAMA_API_KEY", "codewhale auth set --provider ollama")
                 }
+                crate::config::ApiProvider::Volcengine => (
+                    "VOLCENGINE_API_KEY",
+                    "codewhale auth set --provider volcengine",
+                ),
                 crate::config::ApiProvider::Deepseek | crate::config::ApiProvider::DeepseekCN => {
                     ("DEEPSEEK_API_KEY", "codewhale auth set --provider deepseek")
                 }
@@ -1884,9 +1964,12 @@ fn run_setup_status(config: &Config, workspace: &Path) -> Result<()> {
                     crate::config::ApiProvider::Openai => "openai",
                     crate::config::ApiProvider::Atlascloud => "atlascloud",
                     crate::config::ApiProvider::WanjieArk => "wanjie_ark",
+                    crate::config::ApiProvider::Volcengine => "volcengine",
                     crate::config::ApiProvider::Openrouter => "openrouter",
+                    crate::config::ApiProvider::XiaomiMimo => "xiaomi_mimo",
                     crate::config::ApiProvider::Novita => "novita",
                     crate::config::ApiProvider::Fireworks => "fireworks",
+                    crate::config::ApiProvider::Moonshot => "moonshot",
                     crate::config::ApiProvider::Sglang => "sglang",
                     crate::config::ApiProvider::Vllm => "vllm",
                     crate::config::ApiProvider::Ollama => "ollama",
@@ -2047,6 +2130,51 @@ async fn run_doctor(config: &Config, workspace: &Path, config_path_override: Opt
     println!("  rust: {}", rustc_version());
     println!();
 
+    println!("{}", "Updates:".bold());
+    let current_version = env!("CARGO_PKG_VERSION");
+    println!("  · current: v{current_version}");
+    match codewhale_release::latest_release_tag_async(codewhale_release::ReleaseChannel::Stable)
+        .await
+    {
+        Ok(latest_tag) => {
+            match codewhale_release::compare_release_versions(current_version, &latest_tag) {
+                Ok(std::cmp::Ordering::Less) => {
+                    println!(
+                        "  {} latest: {latest_tag}",
+                        "!".truecolor(sky_r, sky_g, sky_b)
+                    );
+                    println!("    Update available. Run `codewhale update` to install.");
+                }
+                Ok(std::cmp::Ordering::Equal) => {
+                    println!(
+                        "  {} latest: {latest_tag}",
+                        "✓".truecolor(aqua_r, aqua_g, aqua_b)
+                    );
+                    println!("    Already up to date.");
+                }
+                Ok(std::cmp::Ordering::Greater) => {
+                    println!("  {} latest: {latest_tag}", "·".dimmed());
+                    println!("    Current build is newer than the latest published release.");
+                }
+                Err(err) => {
+                    println!(
+                        "  {} latest: {latest_tag}",
+                        "!".truecolor(sky_r, sky_g, sky_b)
+                    );
+                    println!("    Version comparison failed: {err}");
+                }
+            }
+        }
+        Err(err) => {
+            println!(
+                "  {} latest release check failed: {err}",
+                "!".truecolor(sky_r, sky_g, sky_b)
+            );
+            println!("    Run `codewhale update --check` to retry.");
+        }
+    }
+    println!();
+
     // Configuration summary
     println!("{}", "Configuration:".bold());
     let config_path = config_path_override
@@ -2072,6 +2200,7 @@ async fn run_doctor(config: &Config, workspace: &Path, config_path_override: Opt
         );
     }
     println!("  workspace: {}", crate::utils::display_path(workspace));
+    println!("  {}", doctor_search_provider_line(config));
 
     // State root (v0.8.44)
     println!();
@@ -2144,6 +2273,11 @@ async fn run_doctor(config: &Config, workspace: &Path, config_path_override: Opt
             "openrouter",
             &["OPENROUTER_API_KEY"][..],
         ),
+        (
+            crate::config::ApiProvider::XiaomiMimo,
+            "xiaomi-mimo",
+            &["XIAOMI_MIMO_API_KEY", "MIMO_API_KEY"][..],
+        ),
         (
             crate::config::ApiProvider::Novita,
             "novita",
@@ -2154,6 +2288,11 @@ async fn run_doctor(config: &Config, workspace: &Path, config_path_override: Opt
             "fireworks",
             &["FIREWORKS_API_KEY"][..],
         ),
+        (
+            crate::config::ApiProvider::Moonshot,
+            "moonshot",
+            &["MOONSHOT_API_KEY", "KIMI_API_KEY"][..],
+        ),
         (
             crate::config::ApiProvider::Sglang,
             "sglang",
@@ -3031,6 +3170,7 @@ fn run_doctor_json(
             "message": strict_tool_mode.message,
             "recommended_base_url": strict_tool_mode.recommended_base_url,
         },
+        "search_provider": doctor_search_provider_json(config),
         "memory": memory_summary,
         "mcp": mcp_summary,
         "skills": {
@@ -3140,6 +3280,38 @@ fn provider_capability_report(config: &Config) -> serde_json::Value {
     })
 }
 
+fn doctor_search_provider_line(config: &Config) -> String {
+    let search_provider = config.search_provider_resolution();
+    let switch_hint = if matches!(
+        (search_provider.provider, search_provider.source),
+        (
+            crate::config::SearchProvider::DuckDuckGo,
+            crate::config::SearchProviderSource::Default
+        )
+    ) {
+        "; set [search] provider = \"bing\" | \"tavily\" | \"bocha\" to switch"
+    } else {
+        ""
+    };
+
+    format!(
+        "search_provider: {} (source: {}{})",
+        search_provider.provider.as_str(),
+        search_provider.source.as_str(),
+        switch_hint
+    )
+}
+
+fn doctor_search_provider_json(config: &Config) -> serde_json::Value {
+    use serde_json::json;
+
+    let search_provider = config.search_provider_resolution();
+    json!({
+        "provider": search_provider.provider.as_str(),
+        "source": search_provider.source.as_str(),
+    })
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct DoctorApiTarget {
     provider: &'static str,
@@ -3725,7 +3897,13 @@ async fn run_pr(
     } else {
         cli.resume.clone()
     };
-    run_interactive(cli, config, resume_session_id, Some(prompt)).await
+    run_interactive(
+        cli,
+        config,
+        resume_session_id,
+        Some(tui::InitialInput::Prefill(prompt)),
+    )
+    .await
 }
 
 /// Return true if `name` resolves to an executable on the current `PATH`.
@@ -4074,11 +4252,17 @@ async fn run_mcp_command(config: &Config, command: McpCommand) -> Result<()> {
             name,
             command,
             url,
+            transport,
             args,
         } => {
             if command.is_none() && url.is_none() {
                 bail!("Provide either --command or --url for `mcp add`.");
             }
+            if let Some(transport) = transport.as_deref() {
+                if !transport.trim().eq_ignore_ascii_case("sse") {
+                    bail!("Unsupported MCP transport '{transport}'. Supported values: sse");
+                }
+            }
             let mut cfg = load_mcp_config(&config_path)?;
             cfg.servers.insert(
                 name.clone(),
@@ -4087,6 +4271,7 @@ async fn run_mcp_command(config: &Config, command: McpCommand) -> Result<()> {
                     args,
                     env: std::collections::HashMap::new(),
                     url,
+                    transport,
                     connect_timeout: None,
                     execute_timeout: None,
                     read_timeout: None,
@@ -4173,6 +4358,7 @@ async fn run_mcp_command(config: &Config, command: McpCommand) -> Result<()> {
                     args,
                     env: std::collections::HashMap::new(),
                     url: None,
+                    transport: None,
                     connect_timeout: None,
                     execute_timeout: None,
                     read_timeout: None,
@@ -4600,6 +4786,20 @@ fn preserve_interrupted_checkpoint_for_explicit_resume(launch_workspace: &Path)
 /// Only explicitly set fields in the project file are applied; everything
 /// else falls back to the global value.
 fn merge_project_config(config: &mut Config, workspace: &Path) {
+    // When the workspace is the user's home directory, the project-scope
+    // config file is also the global config file. Skip the merge to avoid
+    // redundant processing and a misleading "project-scope config key
+    // ignored" warning on every launch from ~.
+    if let Some(home) = effective_home_dir()
+        && let (Ok(w), Ok(h)) = (
+            std::fs::canonicalize(workspace),
+            std::fs::canonicalize(&home),
+        )
+        && w == h
+    {
+        return;
+    }
+
     // v0.8.44: prefer .codewhale/config.toml, fall back to .deepseek/
     let path = workspace
         .join(codewhale_config::CODEWHALE_APP_DIR)
@@ -4651,41 +4851,49 @@ fn merge_project_config(config: &mut Config, workspace: &Path) {
 
     // String fields a project may legitimately override (model,
     // approval/sandbox tightening, notes path, reasoning effort).
-    // Loosening *values* like `approval_policy = "auto"` and
-    // `sandbox_mode = "danger-full-access"` are denied unconditionally
-    // — those are pure escalation regardless of the user's prior
-    // value. Sub-tightening comparisons (e.g. user `"never"` →
-    // project `"on-request"`) stay v0.8.9 follow-up because they
-    // need a richer ordering check.
     for (key, field) in [
         ("model", &mut config.default_text_model),
         ("reasoning_effort", &mut config.reasoning_effort),
-        ("approval_policy", &mut config.approval_policy),
-        ("sandbox_mode", &mut config.sandbox_mode),
         ("notes_path", &mut config.notes_path),
     ] {
         if let Some(v) = table.get(key).and_then(toml::Value::as_str)
             && !v.is_empty()
         {
-            // #417 escalation deny: project cannot push the session
-            // to the loosest values. Other strings flow through the
-            // existing config validator on load.
-            let is_escalation = matches!(
-                (key, v),
-                ("approval_policy", "auto") | ("sandbox_mode", "danger-full-access")
-            );
-            if is_escalation {
-                eprintln!(
-                    "warning: project-scope `{key} = \"{v}\"` is ignored — \
-                     project config cannot escalate to the loosest value. \
-                     (See #417.)"
-                );
-                continue;
-            }
             *field = Some(v.to_string());
         }
     }
 
+    if let Some(v) = table.get("approval_policy").and_then(toml::Value::as_str)
+        && !v.is_empty()
+    {
+        if codewhale_config::project_approval_policy_is_allowed(
+            config.approval_policy.as_deref(),
+            v,
+        ) {
+            config.approval_policy = Some(v.to_string());
+        } else {
+            eprintln!(
+                "warning: project-scope `approval_policy = \"{v}\"` is ignored — \
+                 project config can only tighten the user's approval policy. \
+                 (See #417.)"
+            );
+        }
+    }
+
+    if let Some(v) = table.get("sandbox_mode").and_then(toml::Value::as_str)
+        && !v.is_empty()
+    {
+        if codewhale_config::project_sandbox_mode_is_allowed(config.sandbox_mode.as_deref(), v) {
+            config.sandbox_mode = Some(v.to_string());
+        } else {
+            eprintln!(
+                "warning: project-scope `sandbox_mode = \"{v}\"` is ignored — \
+                 project config can only tighten the user's sandbox mode. \
+                 (See #417.)"
+            );
+        }
+    }
+
     // Numeric / bool fields that benefit from per-project overrides.
     if let Some(v) = table.get("max_subagents").and_then(toml::Value::as_integer)
         && v > 0
@@ -4715,7 +4923,7 @@ async fn run_interactive(
     cli: &Cli,
     config: &Config,
     resume_session_id: Option<String>,
-    initial_input: Option<String>,
+    initial_input: Option<tui::InitialInput>,
 ) -> Result<()> {
     let workspace = cli
         .workspace
@@ -4797,6 +5005,10 @@ async fn run_interactive(
         let _ = manager.cleanup_old_sessions();
     }
 
+    // The `deepseek` launcher forwards `--yolo` to this binary via the
+    // DEEPSEEK_YOLO env var (config.yolo), not as a CLI flag. Honour either.
+    let yolo = cli.yolo || config.yolo.unwrap_or(false);
+
     tui::run_tui(
         config,
         tui::TuiOptions {
@@ -4804,7 +5016,7 @@ async fn run_interactive(
             workspace,
             config_path: cli.config.clone(),
             config_profile: cli.profile.clone(),
-            allow_shell: cli.yolo || config.allow_shell(),
+            allow_shell: yolo || config.allow_shell(),
             use_alt_screen,
             use_mouse_capture,
             use_bracketed_paste,
@@ -4813,9 +5025,9 @@ async fn run_interactive(
             notes_path: config.notes_path(),
             mcp_config_path: config.mcp_config_path(),
             use_memory: config.memory_enabled(),
-            start_in_agent_mode: cli.yolo,
+            start_in_agent_mode: yolo,
             skip_onboarding: cli.skip_onboarding,
-            yolo: cli.yolo, // YOLO mode auto-approves all tool executions
+            yolo, // YOLO mode auto-approves all tool executions
             resume_session_id,
             initial_input,
             max_subagents,
@@ -5088,6 +5300,7 @@ async fn run_exec_agent(
         .lsp
         .clone()
         .map(crate::config::LspConfigToml::into_runtime);
+    let settings = crate::settings::Settings::load().unwrap_or_default();
 
     let engine_config = EngineConfig {
         model: effective_model.clone(),
@@ -5097,9 +5310,14 @@ async fn run_exec_agent(
         notes_path: config.notes_path(),
         mcp_config_path: config.mcp_config_path(),
         skills_dir: config.skills_dir(),
-        instructions: config.instructions_paths(),
+        instructions: config
+            .instructions_paths()
+            .into_iter()
+            .map(Into::into)
+            .collect(),
         project_context_pack_enabled: config.project_context_pack_enabled(),
         translation_enabled: false,
+        show_thinking: settings.show_thinking,
         max_steps: 100,
         max_subagents,
         features: config.features(),
@@ -5108,6 +5326,7 @@ async fn run_exec_agent(
         capacity: crate::core::capacity::CapacityControllerConfig::from_app_config(config),
         todos: new_shared_todo_list(),
         plan_state: new_shared_plan_state(),
+        goal_state: crate::tools::goal::new_shared_goal_state(),
         max_spawn_depth: crate::tools::subagent::DEFAULT_MAX_SPAWN_DEPTH,
         network_policy,
         snapshots_enabled: config.snapshots_config().enabled,
@@ -5119,23 +5338,20 @@ async fn run_exec_agent(
         runtime_services: crate::tools::spec::RuntimeToolServices::default(),
         subagent_model_overrides: config.subagent_model_overrides(),
         subagent_api_timeout: std::time::Duration::from_secs(config.subagent_api_timeout_secs()),
+        prefer_bwrap: config.prefer_bwrap.unwrap_or(false),
         memory_enabled: config.memory_enabled(),
         memory_path: config.memory_path(),
         vision_config: config.vision_model_config(),
         strict_tool_mode: config.strict_tool_mode.unwrap_or(false),
         goal_objective: None,
-        locale_tag: crate::localization::resolve_locale(
-            &crate::settings::Settings::load().unwrap_or_default().locale,
-        )
-        .tag()
-        .to_string(),
+        allowed_tools: None,
+        locale_tag: crate::localization::resolve_locale(&settings.locale)
+            .tag()
+            .to_string(),
         workshop: config.workshop.clone(),
-        search_provider: config
-            .search
-            .as_ref()
-            .and_then(|s| s.provider)
-            .unwrap_or_default(),
+        search_provider: config.search_provider(),
         search_api_key: config.search.as_ref().and_then(|s| s.api_key.clone()),
+        tools_always_load: config.tools_always_load(),
     };
 
     let engine_handle = spawn_engine(engine_config, config);
@@ -5183,6 +5399,7 @@ async fn run_exec_agent(
             mode,
             model: effective_model.clone(),
             goal_objective: None,
+            allowed_tools: None,
             reasoning_effort: effective_reasoning_effort,
             reasoning_effort_auto: auto_model,
             auto_model,
@@ -5190,6 +5407,7 @@ async fn run_exec_agent(
             trust_mode,
             auto_approve,
             translation_enabled: false,
+            show_thinking: settings.show_thinking,
             approval_mode: if auto_approve {
                 crate::tui::approval::ApprovalMode::Auto
             } else {
@@ -5488,6 +5706,53 @@ async fn run_exec_agent(
     Ok(())
 }
 
+#[cfg(test)]
+mod serve_bind_host_tests {
+    use super::*;
+
+    #[test]
+    fn http_defaults_to_loopback() {
+        assert_eq!(
+            resolve_serve_bind_host(false, None),
+            ServeBindHost {
+                host: "127.0.0.1".to_string(),
+                mobile_rebound_to_lan: false,
+            }
+        );
+    }
+
+    #[test]
+    fn mobile_default_rebinds_to_lan_with_warning_flag() {
+        assert_eq!(
+            resolve_serve_bind_host(true, None),
+            ServeBindHost {
+                host: "0.0.0.0".to_string(),
+                mobile_rebound_to_lan: true,
+            }
+        );
+    }
+
+    #[test]
+    fn mobile_respects_explicit_loopback_host() {
+        assert_eq!(
+            resolve_serve_bind_host(true, Some("127.0.0.1".to_string())),
+            ServeBindHost {
+                host: "127.0.0.1".to_string(),
+                mobile_rebound_to_lan: false,
+            }
+        );
+    }
+
+    #[test]
+    fn http_and_mobile_are_mutually_exclusive() {
+        let err = validate_serve_mode_selection(false, true, true, false).unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("--http and --mobile are mutually exclusive")
+        );
+    }
+}
+
 #[cfg(test)]
 mod doctor_endpoint_tests {
     use super::*;
@@ -5630,6 +5895,87 @@ mod doctor_endpoint_tests {
         assert!(report["alias_deprecation"].is_null());
     }
 
+    #[test]
+    fn doctor_search_provider_line_includes_duckduckgo_default_source_and_switch_hint() {
+        let _guard = crate::test_support::lock_test_env();
+        let prev = std::env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { std::env::remove_var("DEEPSEEK_SEARCH_PROVIDER") };
+
+        let line = doctor_search_provider_line(&Config::default());
+
+        match prev {
+            Some(value) => unsafe { std::env::set_var("DEEPSEEK_SEARCH_PROVIDER", value) },
+            None => unsafe { std::env::remove_var("DEEPSEEK_SEARCH_PROVIDER") },
+        }
+        assert!(line.contains("search_provider: duckduckgo"));
+        assert!(line.contains("source: default"));
+        assert!(line.contains("[search] provider"));
+        assert!(line.contains("provider = \"bing\""));
+    }
+
+    #[test]
+    fn doctor_search_provider_json_reports_config_source() {
+        let _guard = crate::test_support::lock_test_env();
+        let prev = std::env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { std::env::remove_var("DEEPSEEK_SEARCH_PROVIDER") };
+        let config = Config {
+            search: Some(crate::config::SearchConfig {
+                provider: Some(crate::config::SearchProvider::DuckDuckGo),
+                api_key: None,
+            }),
+            ..Default::default()
+        };
+
+        let report = doctor_search_provider_json(&config);
+
+        match prev {
+            Some(value) => unsafe { std::env::set_var("DEEPSEEK_SEARCH_PROVIDER", value) },
+            None => unsafe { std::env::remove_var("DEEPSEEK_SEARCH_PROVIDER") },
+        }
+        assert_eq!(report["provider"], "duckduckgo");
+        assert_eq!(report["source"], "config");
+    }
+
+    #[test]
+    fn doctor_search_provider_json_reports_env_override_source() {
+        let _guard = crate::test_support::lock_test_env();
+        let prev = std::env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { std::env::set_var("DEEPSEEK_SEARCH_PROVIDER", "tavily") };
+
+        let report = doctor_search_provider_json(&Config::default());
+
+        match prev {
+            Some(value) => unsafe { std::env::set_var("DEEPSEEK_SEARCH_PROVIDER", value) },
+            None => unsafe { std::env::remove_var("DEEPSEEK_SEARCH_PROVIDER") },
+        }
+        assert_eq!(report["provider"], "tavily");
+        assert_eq!(report["source"], "env override");
+    }
+
+    #[test]
+    fn doctor_search_provider_line_omits_switch_hint_when_bing_is_configured() {
+        let _guard = crate::test_support::lock_test_env();
+        let prev = std::env::var_os("DEEPSEEK_SEARCH_PROVIDER");
+        unsafe { std::env::remove_var("DEEPSEEK_SEARCH_PROVIDER") };
+        let config = Config {
+            search: Some(crate::config::SearchConfig {
+                provider: Some(crate::config::SearchProvider::Bing),
+                api_key: None,
+            }),
+            ..Default::default()
+        };
+
+        let line = doctor_search_provider_line(&config);
+
+        match prev {
+            Some(value) => unsafe { std::env::set_var("DEEPSEEK_SEARCH_PROVIDER", value) },
+            None => unsafe { std::env::remove_var("DEEPSEEK_SEARCH_PROVIDER") },
+        }
+        assert!(line.contains("search_provider: bing"));
+        assert!(line.contains("source: config"));
+        assert!(!line.contains("[search] provider"));
+    }
+
     #[test]
     fn timeout_recovery_keeps_default_deepseek_users_on_default_endpoint() {
         let config = Config::default();
@@ -5673,6 +6019,16 @@ mod terminal_mode_tests {
         assert_eq!(cli.prompt, vec!["hello", "world"]);
     }
 
+    #[test]
+    fn prompt_flag_starts_interactive_submit_input() {
+        let cli = parse_cli(&["codewhale", "-p", "read", "the", "project"]);
+
+        assert_eq!(
+            top_level_prompt_initial_input(&cli.prompt),
+            Some(tui::InitialInput::Submit("read the project".to_string()))
+        );
+    }
+
     #[test]
     fn companion_binary_reports_its_own_name() {
         assert_eq!(Cli::command().get_name(), "codewhale-tui");
@@ -6156,6 +6512,54 @@ mod project_config_tests {
         tmp
     }
 
+    fn with_home_dir<T>(home: &Path, f: impl FnOnce() -> T) -> T {
+        let prev_home = std::env::var_os("HOME");
+        let prev_userprofile = std::env::var_os("USERPROFILE");
+        unsafe {
+            std::env::set_var("HOME", home);
+            std::env::set_var("USERPROFILE", home);
+        }
+        let result = f();
+        unsafe {
+            match prev_home {
+                Some(value) => std::env::set_var("HOME", value),
+                None => std::env::remove_var("HOME"),
+            }
+            match prev_userprofile {
+                Some(value) => std::env::set_var("USERPROFILE", value),
+                None => std::env::remove_var("USERPROFILE"),
+            }
+        }
+        result
+    }
+
+    #[test]
+    fn project_overlay_skips_when_workspace_is_home_directory() {
+        let _guard = crate::test_support::lock_test_env();
+        let tmp = tempdir().expect("tempdir");
+        let project_dir = tmp.path().join(codewhale_config::CODEWHALE_APP_DIR);
+        fs::create_dir_all(&project_dir).expect("mkdir .codewhale");
+        fs::write(
+            project_dir.join("config.toml"),
+            r#"model = "project-override-model""#,
+        )
+        .expect("write project config");
+
+        with_home_dir(tmp.path(), || {
+            let mut config = Config {
+                default_text_model: Some("deepseek-v4-flash".to_string()),
+                ..Config::default()
+            };
+
+            merge_project_config(&mut config, tmp.path());
+
+            assert_eq!(
+                config.default_text_model.as_deref(),
+                Some("deepseek-v4-flash")
+            );
+        });
+    }
+
     #[test]
     fn project_overlay_overrides_model_but_denies_provider() {
         // #417: `provider` is on the deny-list; only the `model`
@@ -6289,6 +6693,42 @@ approval_policy = "auto"
         );
     }
 
+    #[test]
+    fn project_overlay_preserves_user_policy_when_project_tries_intermediate_loosening() {
+        let tmp = workspace_with_project_config(
+            r#"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+"#,
+        );
+        let mut config = Config {
+            approval_policy: Some("never".to_string()),
+            sandbox_mode: Some("read-only".to_string()),
+            ..Config::default()
+        };
+        merge_project_config(&mut config, tmp.path());
+        assert_eq!(config.approval_policy.as_deref(), Some("never"));
+        assert_eq!(config.sandbox_mode.as_deref(), Some("read-only"));
+    }
+
+    #[test]
+    fn project_overlay_can_tighten_user_policy() {
+        let tmp = workspace_with_project_config(
+            r#"
+approval_policy = "never"
+sandbox_mode = "read-only"
+"#,
+        );
+        let mut config = Config {
+            approval_policy: Some("on-request".to_string()),
+            sandbox_mode: Some("workspace-write".to_string()),
+            ..Config::default()
+        };
+        merge_project_config(&mut config, tmp.path());
+        assert_eq!(config.approval_policy.as_deref(), Some("never"));
+        assert_eq!(config.sandbox_mode.as_deref(), Some("read-only"));
+    }
+
     #[test]
     fn project_overlay_overrides_max_subagents_and_allow_shell() {
         let tmp = workspace_with_project_config(
@@ -6470,6 +6910,7 @@ mod doctor_mcp_tests {
             args: args.iter().map(|s| s.to_string()).collect(),
             env: std::collections::HashMap::new(),
             url: url.map(String::from),
+            transport: None,
             connect_timeout: None,
             execute_timeout: None,
             read_timeout: None,
diff --git a/crates/tui/src/mcp.rs b/crates/tui/src/mcp.rs
index e7be32db..e899e593 100644
--- a/crates/tui/src/mcp.rs
+++ b/crates/tui/src/mcp.rs
@@ -85,6 +85,24 @@ fn is_safe_custom_header(key: &str, value: &str) -> bool {
     !value.contains('\r') && !value.contains('\n')
 }
 
+fn apply_safe_custom_headers(
+    mut request: reqwest::RequestBuilder,
+    headers: &HashMap<String, String>,
+) -> reqwest::RequestBuilder {
+    for (key, value) in headers {
+        if !is_safe_custom_header(key, value) {
+            tracing::warn!(
+                target: "mcp",
+                "skipping unsafe MCP header {:?} (empty/control-char/reserved)",
+                key
+            );
+            continue;
+        }
+        request = request.header(key.as_str(), value.as_str());
+    }
+    request
+}
+
 /// Mask a URL so any embedded credentials in the userinfo portion (e.g.
 /// `https://user:secret@host`) are replaced with `***`. Failures fall back to
 /// the original string so we don't lose context — we never want masking to
@@ -230,6 +248,16 @@ pub struct McpServerConfig {
     #[serde(default)]
     pub env: HashMap<String, String>,
     pub url: Option<String>,
+    /// Optional explicit HTTP transport override.
+    ///
+    /// By default URL-based MCP servers use Streamable HTTP first and fall
+    /// back to legacy SSE only when the server rejects Streamable HTTP with
+    /// a known incompatible status. Set this to `"sse"` for legacy SSE
+    /// endpoints that must start with a long-lived GET endpoint discovery
+    /// stream and cannot accept an initial POST to the configured URL.
+    #[serde(default)]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transport: Option<String>,
     #[serde(default)]
     pub connect_timeout: Option<u64>,
     #[serde(default)]
@@ -537,6 +565,7 @@ impl Drop for StdioTransport {
 pub struct SseTransport {
     client: reqwest::Client,
     base_url: String,
+    headers: HashMap<String, String>,
     endpoint_url: Option<String>,
     receiver: tokio::sync::mpsc::UnboundedReceiver<SseInbound>,
     pending_messages: VecDeque<Vec<u8>>,
@@ -551,6 +580,7 @@ struct HttpTransport {
     mode: HttpTransportMode,
     client: reqwest::Client,
     base_url: String,
+    headers: HashMap<String, String>,
     cancel_token: tokio_util::sync::CancellationToken,
     endpoint_timeout: Duration,
 }
@@ -580,6 +610,7 @@ struct StreamableHttpTransport {
 #[derive(Debug)]
 enum StreamableSendError {
     Incompatible(String),
+    StaleSession(String),
     Other(anyhow::Error),
 }
 
@@ -587,12 +618,14 @@ impl SseTransport {
     pub async fn connect(
         client: reqwest::Client,
         url: String,
+        headers: HashMap<String, String>,
         cancel_token: tokio_util::sync::CancellationToken,
         endpoint_timeout: Duration,
     ) -> Result<Self> {
         let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
         let client_clone = client.clone();
         let url_clone = url.clone();
+        let headers_clone = headers.clone();
         let wait_cancel_token = cancel_token.clone();
 
         tokio::spawn(async move {
@@ -603,6 +636,7 @@ impl SseTransport {
             let result = std::panic::AssertUnwindSafe(Self::run_sse_loop(
                 client_clone,
                 url_clone,
+                headers_clone,
                 tx,
                 cancel_token,
             ))
@@ -629,6 +663,7 @@ impl SseTransport {
         let mut transport = Self {
             client,
             base_url: url,
+            headers,
             endpoint_url: None,
             receiver: rx,
             pending_messages: VecDeque::new(),
@@ -642,18 +677,22 @@ impl SseTransport {
     async fn run_sse_loop(
         client: reqwest::Client,
         url: String,
+        headers: HashMap<String, String>,
         tx: tokio::sync::mpsc::UnboundedSender<SseInbound>,
         cancel_token: tokio_util::sync::CancellationToken,
     ) -> Result<()> {
-        let response = with_default_mcp_http_headers(client.get(&url), false)
-            .send()
-            .await
-            .with_context(|| {
-                format!(
-                    "MCP SSE connect failed (transport=http url={})",
-                    mask_url_secrets(&url),
-                )
-            })?;
+        let response = apply_safe_custom_headers(
+            with_default_mcp_http_headers(client.get(&url), false),
+            &headers,
+        )
+        .send()
+        .await
+        .with_context(|| {
+            format!(
+                "MCP SSE connect failed (transport=http url={})",
+                mask_url_secrets(&url),
+            )
+        })?;
         let status = response.status();
         if !status.is_success() {
             let body_excerpt = bounded_body_excerpt(response, ERROR_BODY_PREVIEW_BYTES).await;
@@ -783,10 +822,11 @@ impl HttpTransport {
             mode: HttpTransportMode::Streamable(StreamableHttpTransport::new(
                 client.clone(),
                 url.clone(),
-                headers,
+                headers.clone(),
             )),
             client,
             base_url: url,
+            headers,
             cancel_token,
             endpoint_timeout,
         }
@@ -796,6 +836,7 @@ impl HttpTransport {
         let mut sse = SseTransport::connect(
             self.client.clone(),
             self.base_url.clone(),
+            self.headers.clone(),
             self.cancel_token.clone(),
             self.endpoint_timeout,
         )
@@ -836,19 +877,10 @@ impl HttpTransport {
             HttpTransportMode::Sse(_) => return Ok(()),
         };
 
-        let mut request = transport.client.get(&transport.url);
-        request = with_default_mcp_http_headers(request, false);
-        for (key, value) in &transport.headers {
-            if !is_safe_custom_header(key, value) {
-                tracing::warn!(
-                    target: "mcp",
-                    "skipping unsafe MCP header {:?} (empty/control-char/reserved)",
-                    key
-                );
-                continue;
-            }
-            request = request.header(key.as_str(), value.as_str());
-        }
+        let request = apply_safe_custom_headers(
+            with_default_mcp_http_headers(transport.client.get(&transport.url), false),
+            &transport.headers,
+        );
         let response = tokio::time::timeout(Duration::from_secs(5), request.send())
             .await
             .map_err(|_| anyhow::anyhow!("GET timeout"))?
@@ -891,6 +923,19 @@ impl McpTransport for HttpTransport {
                     );
                     self.switch_to_sse_and_send(msg).await
                 }
+                Err(StreamableSendError::StaleSession(detail)) => {
+                    if let HttpTransportMode::Streamable(transport) = &mut self.mode {
+                        tracing::debug!(
+                            target: "mcp",
+                            error = %detail,
+                            "MCP Streamable HTTP session expired; clearing cached session ID"
+                        );
+                        transport.session_id = None;
+                    }
+                    Err(anyhow::anyhow!(
+                        "MCP Streamable HTTP session expired; retry with a new session required ({detail})"
+                    ))
+                }
                 Err(StreamableSendError::Other(err)) => Err(err),
             },
             HttpTransportMode::Sse(transport) => transport.send(msg).await,
@@ -923,29 +968,12 @@ impl StreamableHttpTransport {
     }
 
     async fn send(&mut self, msg: Vec<u8>) -> std::result::Result<(), StreamableSendError> {
-        let mut request = with_default_mcp_http_headers(self.client.post(&self.url), true);
-        // Apply user-configured custom headers. Skip:
-        //   * empty / whitespace-only keys (would produce reqwest builder
-        //     errors mid-request and abort the whole connection);
-        //   * keys that duplicate the framing we already set (`Accept`,
-        //     `Content-Type`) so a stray entry can't break protocol
-        //     negotiation;
-        //   * values containing CR/LF, which would enable response-
-        //     splitting style requests on a misbehaving proxy.
-        // reqwest itself rejects malformed header names/values; the
-        // duplicates and control-char filter is purely defense in
-        // depth.
-        for (key, value) in &self.headers {
-            if !is_safe_custom_header(key, value) {
-                tracing::warn!(
-                    target: "mcp",
-                    "skipping unsafe MCP header {:?} (empty/control-char/reserved)",
-                    key
-                );
-                continue;
-            }
-            request = request.header(key.as_str(), value.as_str());
-        }
+        // Apply user-configured custom headers after protocol framing so
+        // reserved Accept / Content-Type overrides can be filtered out.
+        let mut request = apply_safe_custom_headers(
+            with_default_mcp_http_headers(self.client.post(&self.url), true),
+            &self.headers,
+        );
         // Attach any previously captured session ID per the Streamable
         // HTTP spec so the server can correlate this request to the
         // existing session.
@@ -978,6 +1006,13 @@ impl StreamableHttpTransport {
 
         if !status.is_success() {
             let body_excerpt = bounded_body_excerpt(response, ERROR_BODY_PREVIEW_BYTES).await;
+            if self.session_id.is_some()
+                && is_streamable_http_stale_session_status(status, &body_excerpt)
+            {
+                return Err(StreamableSendError::StaleSession(format!(
+                    "status={status} body={body_excerpt}"
+                )));
+            }
             if is_streamable_http_incompatible_status(status) {
                 return Err(StreamableSendError::Incompatible(format!(
                     "status={status} body={body_excerpt}"
@@ -1044,6 +1079,30 @@ fn is_streamable_http_incompatible_status(status: StatusCode) -> bool {
     )
 }
 
+fn is_streamable_http_stale_session_status(status: StatusCode, body_excerpt: &str) -> bool {
+    if status == StatusCode::NOT_FOUND {
+        return true;
+    }
+    if status != StatusCode::BAD_REQUEST && status != StatusCode::UNAUTHORIZED {
+        return false;
+    }
+    let body = body_excerpt.to_ascii_lowercase();
+    body.contains("session") && (body.contains("expired") || body.contains("invalid"))
+}
+
+fn is_mcp_stale_session_body(body: &str) -> bool {
+    let body = body.to_ascii_lowercase();
+    body.contains("session") && (body.contains("expired") || body.contains("invalid"))
+}
+
+fn is_mcp_stale_session_error(err: &anyhow::Error) -> bool {
+    let err = format!("{err:#}");
+    err.contains("MCP Streamable HTTP session expired")
+        || err.contains("MCP session expired")
+        || err.contains("SSE transport closed")
+        || is_mcp_stale_session_body(&err)
+}
+
 fn parse_sse_message_data(body: &str) -> Vec<Vec<u8>> {
     let normalized = body.replace("\r\n", "\n");
     let mut messages = Vec::new();
@@ -1087,6 +1146,36 @@ fn sse_field_value<'a>(line: &'a str, field: &str) -> Option<&'a str> {
     Some(value.strip_prefix(' ').unwrap_or(value))
 }
 
+fn is_legacy_sse_transport(config: &McpServerConfig) -> bool {
+    config
+        .transport
+        .as_deref()
+        .map(|transport| transport.trim().eq_ignore_ascii_case("sse"))
+        .unwrap_or(false)
+}
+
+fn validate_mcp_transport(transport: Option<&str>) -> Result<()> {
+    let Some(transport) = transport else {
+        return Ok(());
+    };
+    if transport.trim().eq_ignore_ascii_case("sse") {
+        return Ok(());
+    }
+    anyhow::bail!("Unsupported MCP transport '{transport}'. Supported values: sse");
+}
+
+fn response_id_matches(id: Option<&serde_json::Value>, expected_id: &str) -> bool {
+    let Some(id) = id else {
+        return false;
+    };
+    if id.as_str() == Some(expected_id) {
+        return true;
+    }
+    id.as_u64()
+        .map(|id| id.to_string() == expected_id)
+        .unwrap_or(false)
+}
+
 #[async_trait::async_trait]
 impl McpTransport for SseTransport {
     async fn send(&mut self, msg: Vec<u8>) -> Result<()> {
@@ -1094,12 +1183,30 @@ impl McpTransport for SseTransport {
             .endpoint_url
             .as_ref()
             .context("SSE endpoint not yet discovered")?;
-        let response = with_default_mcp_http_headers(self.client.post(endpoint), true)
-            .body(msg)
-            .send()
-            .await?;
-        if !response.status().is_success() {
-            anyhow::bail!("Failed to send message via SSE POST: {}", response.status());
+        let response = apply_safe_custom_headers(
+            with_default_mcp_http_headers(self.client.post(endpoint), true),
+            &self.headers,
+        )
+        .body(msg)
+        .send()
+        .await?;
+        let status = response.status();
+        if !status.is_success() {
+            let body_excerpt = bounded_body_excerpt(response, ERROR_BODY_PREVIEW_BYTES).await;
+            if is_mcp_stale_session_body(&body_excerpt) {
+                anyhow::bail!(
+                    "MCP session expired (transport=sse endpoint={} status={}): {}",
+                    mask_url_secrets(endpoint),
+                    status,
+                    body_excerpt
+                );
+            }
+            anyhow::bail!(
+                "MCP SSE POST rejected (transport=sse endpoint={} status={}): {}",
+                mask_url_secrets(endpoint),
+                status,
+                body_excerpt
+            );
         }
         Ok(())
     }
@@ -1212,27 +1319,40 @@ impl McpConnection {
                 }
             }
             let client = client_builder.build()?;
-            let mut http = HttpTransport::new(
-                client,
-                url.clone(),
-                config.headers.clone(),
-                cancel_token.clone(),
-                Duration::from_secs(connect_timeout_secs),
-            );
-            // Best-effort session preflight for servers that require
-            // a session ID on every POST including `initialize`
-            // (e.g. Hindsight, #1629). Failures are non-fatal — the
-            // `initialize` POST will proceed and may capture a session
-            // ID from the response instead.
-            if let Err(e) = http.try_establish_session().await {
-                tracing::debug!(
-                    target: "mcp",
-                    server = %name,
-                    error = %e,
-                    "session-establishment GET skipped; proceeding with POST initialize"
+            if is_legacy_sse_transport(&config) {
+                Box::new(
+                    SseTransport::connect(
+                        client,
+                        url.clone(),
+                        config.headers.clone(),
+                        cancel_token.clone(),
+                        Duration::from_secs(connect_timeout_secs),
+                    )
+                    .await?,
+                )
+            } else {
+                let mut http = HttpTransport::new(
+                    client,
+                    url.clone(),
+                    config.headers.clone(),
+                    cancel_token.clone(),
+                    Duration::from_secs(connect_timeout_secs),
                 );
+                // Best-effort session preflight for servers that require
+                // a session ID on every POST including `initialize`
+                // (e.g. Hindsight, #1629). Failures are non-fatal — the
+                // `initialize` POST will proceed and may capture a session
+                // ID from the response instead.
+                if let Err(e) = http.try_establish_session().await {
+                    tracing::debug!(
+                        target: "mcp",
+                        server = %name,
+                        error = %e,
+                        "session-establishment GET skipped; proceeding with POST initialize"
+                    );
+                }
+                Box::new(http)
             }
-            Box::new(http)
         } else if let Some(command) = &config.command {
             let mut cmd = tokio::process::Command::new(command);
             cmd.args(&config.args)
@@ -1320,7 +1440,7 @@ impl McpConnection {
         let init_id = self.next_id();
         self.send(serde_json::json!({
             "jsonrpc": "2.0",
-            "id": init_id,
+            "id": &init_id,
             "method": "initialize",
             "params": {
                 "protocolVersion": "2024-11-05",
@@ -1371,7 +1491,7 @@ impl McpConnection {
             };
             self.send(serde_json::json!({
                 "jsonrpc": "2.0",
-                "id": list_id,
+                "id": &list_id,
                 "method": "tools/list",
                 "params": params
             }))
@@ -1423,7 +1543,7 @@ impl McpConnection {
             };
             self.send(serde_json::json!({
                 "jsonrpc": "2.0",
-                "id": list_id,
+                "id": &list_id,
                 "method": "resources/list",
                 "params": params
             }))
@@ -1467,7 +1587,7 @@ impl McpConnection {
             };
             self.send(serde_json::json!({
                 "jsonrpc": "2.0",
-                "id": list_id,
+                "id": &list_id,
                 "method": "resources/templates/list",
                 "params": params
             }))
@@ -1515,7 +1635,7 @@ impl McpConnection {
             };
             self.send(serde_json::json!({
                 "jsonrpc": "2.0",
-                "id": list_id,
+                "id": &list_id,
                 "method": "prompts/list",
                 "params": params
             }))
@@ -1618,7 +1738,7 @@ impl McpConnection {
         let call_id = self.next_id();
         self.send(serde_json::json!({
             "jsonrpc": "2.0",
-            "id": call_id,
+            "id": &call_id,
             "method": method,
             "params": params
         }))
@@ -1689,8 +1809,8 @@ impl McpConnection {
         self.state
     }
 
-    fn next_id(&self) -> u64 {
-        self.request_id.fetch_add(1, Ordering::SeqCst)
+    fn next_id(&self) -> String {
+        self.request_id.fetch_add(1, Ordering::SeqCst).to_string()
     }
 
     async fn send(&mut self, msg: serde_json::Value) -> Result<()> {
@@ -1698,7 +1818,7 @@ impl McpConnection {
         self.transport.send(bytes).await
     }
 
-    async fn recv(&mut self, expected_id: u64) -> Result<serde_json::Value> {
+    async fn recv(&mut self, expected_id: String) -> Result<serde_json::Value> {
         loop {
             let bytes = self.transport.recv().await.inspect_err(|_e| {
                 self.state = ConnectionState::Disconnected;
@@ -1707,8 +1827,16 @@ impl McpConnection {
                 format!("Invalid MCP JSON-RPC message from server '{}'", self.name)
             })?;
 
-            // Check if this is a response with the expected id
-            if value.get("id").and_then(serde_json::Value::as_u64) == Some(expected_id) {
+            // Check if this is a response with the expected id. We emit
+            // string IDs because some MCP gateways reject numeric JSON-RPC
+            // IDs, but accept numeric echoes for compatibility with older
+            // servers and tests.
+            if response_id_matches(value.get("id"), &expected_id) {
+                if let Some(error) = value.get("error") {
+                    if is_mcp_stale_session_body(&error.to_string()) {
+                        anyhow::bail!("MCP session expired: {error}");
+                    }
+                }
                 return Ok(value);
             }
             // Skip notifications (no id) and responses with different ids
@@ -2289,7 +2417,26 @@ impl McpPool {
             anyhow::bail!("MCP tool '{tool_name}' is disabled for server '{server_name}'");
         }
         let timeout = conn.config().effective_execute_timeout(&global_timeouts);
-        conn.call_tool(tool_name, arguments, timeout).await
+        match conn.call_tool(tool_name, arguments.clone(), timeout).await {
+            Ok(result) => Ok(result),
+            Err(err) if is_mcp_stale_session_error(&err) => {
+                tracing::debug!(
+                    target: "mcp",
+                    server = server_name,
+                    tool = tool_name,
+                    error = %err,
+                    "retrying MCP tool call after stale session"
+                );
+                self.connections.remove(server_name);
+                let conn = self.get_or_connect(server_name).await?;
+                if !conn.config().is_tool_enabled(tool_name) {
+                    anyhow::bail!("MCP tool '{tool_name}' is disabled for server '{server_name}'");
+                }
+                let timeout = conn.config().effective_execute_timeout(&global_timeouts);
+                conn.call_tool(tool_name, arguments, timeout).await
+            }
+            Err(err) => Err(err),
+        }
     }
 
     /// Get list of configured server names
@@ -2453,6 +2600,7 @@ fn mcp_template_json() -> Result<String> {
             args: vec!["./path/to/your-mcp-server.js".to_string()],
             env: HashMap::new(),
             url: None,
+            transport: None,
             connect_timeout: None,
             execute_timeout: None,
             read_timeout: None,
@@ -2493,10 +2641,12 @@ pub fn add_server_config(
     command: Option<String>,
     url: Option<String>,
     args: Vec<String>,
+    transport: Option<String>,
 ) -> Result<()> {
     if command.is_none() && url.is_none() {
         anyhow::bail!("Provide either a command or URL for MCP server '{name}'.");
     }
+    validate_mcp_transport(transport.as_deref())?;
     let mut cfg = load_config(path)?;
     cfg.servers.insert(
         name,
@@ -2505,6 +2655,7 @@ pub fn add_server_config(
             args,
             env: HashMap::new(),
             url,
+            transport,
             connect_timeout: None,
             execute_timeout: None,
             read_timeout: None,
@@ -2589,7 +2740,11 @@ fn snapshot_from_config(
         .iter()
         .map(|(name, server)| {
             let transport = if server.url.is_some() {
-                "http/sse"
+                if is_legacy_sse_transport(server) {
+                    "sse"
+                } else {
+                    "http/sse"
+                }
             } else {
                 "stdio"
             };
@@ -2800,6 +2955,7 @@ mod tests {
             args: vec!["server.js".into()],
             env: HashMap::new(),
             url: None,
+            transport: None,
             connect_timeout: None,
             execute_timeout: None,
             read_timeout: None,
@@ -2960,6 +3116,7 @@ mod tests {
             Some("node".to_string()),
             None,
             vec!["server.js".to_string()],
+            None,
         )
         .unwrap();
         set_server_enabled(&path, "local", false).unwrap();
@@ -2977,6 +3134,54 @@ mod tests {
         assert!(removed.servers.iter().all(|server| server.name != "local"));
     }
 
+    #[test]
+    fn test_mcp_config_adds_explicit_sse_transport() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("mcp.json");
+
+        add_server_config(
+            &path,
+            "legacy".to_string(),
+            None,
+            Some("https://example.com/v1/mcp/sse".to_string()),
+            Vec::new(),
+            Some("sse".to_string()),
+        )
+        .unwrap();
+
+        let cfg = load_config(&path).unwrap();
+        assert_eq!(
+            cfg.servers
+                .get("legacy")
+                .and_then(|server| server.transport.as_deref()),
+            Some("sse")
+        );
+
+        let snapshot = manager_snapshot_from_config(&path, false).unwrap();
+        assert_eq!(snapshot.servers[0].transport, "sse");
+    }
+
+    #[test]
+    fn test_mcp_config_rejects_unknown_transport() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("mcp.json");
+
+        let err = add_server_config(
+            &path,
+            "bad".to_string(),
+            None,
+            Some("https://example.com/mcp".to_string()),
+            Vec::new(),
+            Some("streamable".to_string()),
+        )
+        .expect_err("unknown transport should fail");
+
+        assert!(
+            format!("{err:#}").contains("Unsupported MCP transport"),
+            "got: {err:#}"
+        );
+    }
+
     #[test]
     fn test_server_effective_timeouts() {
         let global = McpTimeouts::default();
@@ -2986,6 +3191,7 @@ mod tests {
             args: vec![],
             env: HashMap::new(),
             url: None,
+            transport: None,
             connect_timeout: Some(20),
             execute_timeout: None,
             read_timeout: Some(180),
@@ -3096,6 +3302,7 @@ mod tests {
             args: Vec::new(),
             env: HashMap::new(),
             url: None,
+            transport: None,
             connect_timeout: None,
             execute_timeout: None,
             read_timeout: None,
@@ -3161,7 +3368,7 @@ mod tests {
         let sent = sent.lock().unwrap();
         assert_eq!(sent.len(), 1);
         assert_eq!(sent[0]["jsonrpc"], "2.0");
-        assert_eq!(sent[0]["id"], 1);
+        assert_eq!(sent[0]["id"], "1");
         assert_eq!(sent[0]["method"], "tools/call");
     }
 
@@ -3265,6 +3472,7 @@ mod tests {
                 args: vec!["hi".into()],
                 env: Default::default(),
                 url: None,
+                transport: None,
                 connect_timeout: None,
                 execute_timeout: None,
                 read_timeout: None,
@@ -3326,6 +3534,137 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn mcp_pool_call_tool_preserves_tool_names_with_dashes() {
+        let sent = Arc::new(Mutex::new(Vec::new()));
+        let transport = ScriptedValueTransport {
+            sent: Arc::clone(&sent),
+            responses: VecDeque::from([json_frame(serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 1,
+                "result": {"ok": true}
+            }))]),
+        };
+        let mut conn = test_connection(Box::new(transport));
+        conn.name = "dephy".to_string();
+        conn.tools = vec![McpTool {
+            name: "company--search".to_string(),
+            description: None,
+            input_schema: serde_json::json!({}),
+        }];
+
+        let mut pool = McpPool::new(McpConfig {
+            timeouts: McpTimeouts::default(),
+            servers: HashMap::new(),
+        });
+        pool.connections.insert("dephy".to_string(), conn);
+
+        let result = pool
+            .call_tool(
+                "mcp_dephy_company--search",
+                serde_json::json!({"query": "dephy"}),
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(result, serde_json::json!({"ok": true}));
+        let sent = sent.lock().unwrap();
+        assert_eq!(sent[0]["method"], "tools/call");
+        assert_eq!(sent[0]["params"]["name"], "company--search");
+        assert_eq!(
+            sent[0]["params"]["arguments"],
+            serde_json::json!({"query": "dephy"})
+        );
+    }
+
+    #[tokio::test]
+    async fn json_rpc_session_error_is_marked_stale() {
+        let sent = Arc::new(Mutex::new(Vec::new()));
+        let transport = ScriptedValueTransport {
+            sent: Arc::clone(&sent),
+            responses: VecDeque::from([json_frame(serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 1,
+                "error": {
+                    "code": -32001,
+                    "message": "MCP session expired"
+                }
+            }))]),
+        };
+        let mut conn = test_connection(Box::new(transport));
+
+        let err = conn
+            .call_tool("search", serde_json::json!({"query": "dephy"}), 1)
+            .await
+            .expect_err("session error should fail");
+
+        assert!(
+            is_mcp_stale_session_error(&err),
+            "JSON-RPC session error should be retryable, got: {err:#}"
+        );
+    }
+
+    #[test]
+    fn sse_transport_closed_is_retryable() {
+        let err = anyhow::anyhow!("SSE transport closed");
+        assert!(
+            is_mcp_stale_session_error(&err),
+            "closed SSE stream should force reconnect before retry"
+        );
+    }
+
+    #[tokio::test]
+    async fn discover_all_ignores_unsupported_optional_capabilities() {
+        let sent = Arc::new(Mutex::new(Vec::new()));
+        let transport = ScriptedValueTransport {
+            sent: Arc::clone(&sent),
+            responses: VecDeque::from([
+                json_frame(serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": 1,
+                    "result": {
+                        "tools": [
+                            { "name": "search", "inputSchema": {} }
+                        ]
+                    }
+                })),
+                json_frame(serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": 2,
+                    "error": {
+                        "code": -32601,
+                        "message": "resources not supported"
+                    }
+                })),
+                json_frame(serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": 3,
+                    "error": {
+                        "code": -32601,
+                        "message": "resource templates not supported"
+                    }
+                })),
+                json_frame(serde_json::json!({
+                    "jsonrpc": "2.0",
+                    "id": 4,
+                    "error": {
+                        "code": -32601,
+                        "message": "prompts not supported"
+                    }
+                })),
+            ]),
+        };
+        let mut conn = test_connection(Box::new(transport));
+
+        conn.discover_all().await.expect("discover");
+
+        assert_eq!(conn.tools.len(), 1);
+        assert_eq!(conn.tools[0].name, "search");
+        assert!(conn.resources.is_empty());
+        assert!(conn.resource_templates.is_empty());
+        assert!(conn.prompts.is_empty());
+    }
+
     /// #1244: when an MCP stdio server fails to spawn, the underlying OS
     /// error (e.g. ENOENT for a missing binary) must reach the user via the
     /// snapshot.error string. Regression test for `err.to_string()` dropping
@@ -3377,6 +3716,33 @@ mod tests {
         assert!(value.get("result").is_some());
     }
 
+    #[test]
+    fn response_id_matches_string_and_numeric_echoes() {
+        assert!(response_id_matches(Some(&serde_json::json!("1")), "1"));
+        assert!(response_id_matches(Some(&serde_json::json!(1)), "1"));
+        assert!(!response_id_matches(Some(&serde_json::json!("2")), "1"));
+    }
+
+    #[test]
+    fn legacy_sse_transport_requires_explicit_config() {
+        let mut server = test_server_config();
+        server.url = Some("https://example.com/mcp/abc/sse".to_string());
+
+        assert!(
+            !is_legacy_sse_transport(&server),
+            "/sse paths must not force legacy SSE without an explicit transport override"
+        );
+
+        server.transport = Some("sse".to_string());
+        assert!(is_legacy_sse_transport(&server));
+
+        server.transport = Some("SSE".to_string());
+        assert!(is_legacy_sse_transport(&server));
+
+        server.transport = Some("http".to_string());
+        assert!(!is_legacy_sse_transport(&server));
+    }
+
     #[test]
     fn find_sse_event_separator_accepts_lf_and_crlf() {
         assert_eq!(
@@ -3502,6 +3868,7 @@ mod tests {
             args: vec![],
             env: HashMap::new(),
             url: Some(format!("http://{addr}/mcp")),
+            transport: None,
             connect_timeout: Some(2),
             execute_timeout: None,
             read_timeout: None,
@@ -3768,10 +4135,15 @@ mod tests {
 
         let client = reqwest::Client::new();
         let url = format!("http://{addr}/sse");
-        let mut transport =
-            SseTransport::connect(client, url, cancel_token.clone(), Duration::from_secs(2))
-                .await
-                .unwrap();
+        let mut transport = SseTransport::connect(
+            client,
+            url,
+            HashMap::new(),
+            cancel_token.clone(),
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap();
 
         transport
             .send(json_frame(serde_json::json!({
@@ -3853,10 +4225,15 @@ mod tests {
 
         let client = reqwest::Client::new();
         let url = format!("http://{addr}/sse");
-        let mut transport =
-            SseTransport::connect(client, url, cancel_token.clone(), Duration::from_secs(2))
-                .await
-                .unwrap();
+        let mut transport = SseTransport::connect(
+            client,
+            url,
+            HashMap::new(),
+            cancel_token.clone(),
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap();
 
         transport
             .send(json_frame(serde_json::json!({
@@ -3876,6 +4253,620 @@ mod tests {
         server.abort();
     }
 
+    #[tokio::test]
+    async fn sse_transport_applies_custom_headers_to_get_and_post() {
+        use std::sync::{
+            Arc,
+            atomic::{AtomicBool, Ordering as AtomicOrdering},
+        };
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::TcpListener;
+
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let get_header_seen = Arc::new(AtomicBool::new(false));
+        let post_header_seen = Arc::new(AtomicBool::new(false));
+        let server_get_header_seen = Arc::clone(&get_header_seen);
+        let server_post_header_seen = Arc::clone(&post_header_seen);
+        let cancel_token = tokio_util::sync::CancellationToken::new();
+        let server_cancel = cancel_token.clone();
+
+        let server = tokio::spawn(async move {
+            loop {
+                let Ok((mut socket, _)) = listener.accept().await else {
+                    break;
+                };
+                let get_header_seen = Arc::clone(&server_get_header_seen);
+                let post_header_seen = Arc::clone(&server_post_header_seen);
+                let server_cancel = server_cancel.clone();
+                tokio::spawn(async move {
+                    let mut request = Vec::new();
+                    let mut buf = [0; 1024];
+                    loop {
+                        let n = socket.read(&mut buf).await.unwrap();
+                        if n == 0 {
+                            return;
+                        }
+                        request.extend_from_slice(&buf[..n]);
+                        if request.windows(4).any(|window| window == b"\r\n\r\n") {
+                            break;
+                        }
+                    }
+                    let request = String::from_utf8_lossy(&request);
+                    let request_lower = request.to_lowercase();
+                    if request.starts_with("GET /sse ") {
+                        if request_lower.contains("x-custom-auth: my-test-token") {
+                            get_header_seen.store(true, AtomicOrdering::SeqCst);
+                        }
+                        socket
+                            .write_all(
+                                b"HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\n\r\n",
+                            )
+                            .await
+                            .unwrap();
+                        socket
+                            .write_all(b"event: endpoint\ndata: /messages\n\n")
+                            .await
+                            .unwrap();
+                        server_cancel.cancelled().await;
+                    } else if request.starts_with("POST /messages ") {
+                        if request_lower.contains("x-custom-auth: my-test-token") {
+                            post_header_seen.store(true, AtomicOrdering::SeqCst);
+                        }
+                        socket
+                            .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n")
+                            .await
+                            .unwrap();
+                    }
+                });
+            }
+        });
+
+        let client = reqwest::Client::new();
+        let url = format!("http://{addr}/sse");
+        let mut headers = HashMap::new();
+        headers.insert("X-Custom-Auth".to_string(), "my-test-token".to_string());
+        let mut transport = SseTransport::connect(
+            client,
+            url,
+            headers,
+            cancel_token.clone(),
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap();
+
+        transport
+            .send(json_frame(serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "initialize"
+            })))
+            .await
+            .unwrap();
+
+        assert!(
+            get_header_seen.load(AtomicOrdering::SeqCst),
+            "legacy SSE GET must include user-configured custom headers"
+        );
+        assert!(
+            post_header_seen.load(AtomicOrdering::SeqCst),
+            "legacy SSE POST must include user-configured custom headers"
+        );
+
+        cancel_token.cancel();
+        server.abort();
+    }
+
+    #[tokio::test]
+    async fn sse_post_error_includes_response_body_excerpt() {
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::TcpListener;
+
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let cancel_token = tokio_util::sync::CancellationToken::new();
+        let server_cancel = cancel_token.clone();
+
+        let server = tokio::spawn(async move {
+            loop {
+                let Ok((mut socket, _)) = listener.accept().await else {
+                    break;
+                };
+                let server_cancel = server_cancel.clone();
+                tokio::spawn(async move {
+                    let mut request = Vec::new();
+                    let mut buf = [0; 1024];
+                    loop {
+                        let n = socket.read(&mut buf).await.unwrap();
+                        if n == 0 {
+                            return;
+                        }
+                        request.extend_from_slice(&buf[..n]);
+                        if request.windows(4).any(|window| window == b"\r\n\r\n") {
+                            break;
+                        }
+                    }
+                    let request = String::from_utf8_lossy(&request);
+                    if request.starts_with("GET /sse ") {
+                        socket
+                            .write_all(
+                                b"HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\n\r\n",
+                            )
+                            .await
+                            .unwrap();
+                        socket
+                            .write_all(b"event: endpoint\ndata: /messages\n\n")
+                            .await
+                            .unwrap();
+                        server_cancel.cancelled().await;
+                    } else if request.starts_with("POST /messages ") {
+                        socket
+                            .write_all(
+                                b"HTTP/1.1 400 Bad Request\r\nContent-Type: application/json\r\nContent-Length: 25\r\n\r\n{\"error\":\"missing query\"}",
+                            )
+                            .await
+                            .unwrap();
+                    }
+                });
+            }
+        });
+
+        let client = reqwest::Client::new();
+        let url = format!("http://{addr}/sse");
+        let mut transport = SseTransport::connect(
+            client,
+            url,
+            HashMap::new(),
+            cancel_token.clone(),
+            Duration::from_secs(2),
+        )
+        .await
+        .unwrap();
+
+        let err = transport
+            .send(json_frame(serde_json::json!({
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "initialize"
+            })))
+            .await
+            .expect_err("POST rejection should be returned");
+        let err = format!("{err:#}");
+        assert!(
+            err.contains("400 Bad Request") && err.contains("missing query"),
+            "SSE POST error should include status and body, got: {err}"
+        );
+
+        cancel_token.cancel();
+        server.abort();
+    }
+
+    #[tokio::test]
+    async fn streamable_http_stale_session_reconnects_and_retries_tool_call() {
+        use std::sync::atomic::{AtomicUsize, Ordering as AtomicOrdering};
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::TcpListener;
+
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let get_count = Arc::new(AtomicUsize::new(0));
+        let stale_seen = Arc::new(AtomicBool::new(false));
+        let success_seen = Arc::new(AtomicBool::new(false));
+        let server_get_count = Arc::clone(&get_count);
+        let server_stale_seen = Arc::clone(&stale_seen);
+        let server_success_seen = Arc::clone(&success_seen);
+
+        let server = tokio::spawn(async move {
+            loop {
+                let Ok((mut socket, _)) = listener.accept().await else {
+                    break;
+                };
+                let get_count = Arc::clone(&server_get_count);
+                let stale_seen = Arc::clone(&server_stale_seen);
+                let success_seen = Arc::clone(&server_success_seen);
+                tokio::spawn(async move {
+                    let mut request = Vec::new();
+                    let mut buf = [0; 4096];
+                    let header_end = loop {
+                        let n = socket.read(&mut buf).await.unwrap();
+                        if n == 0 {
+                            return;
+                        }
+                        request.extend_from_slice(&buf[..n]);
+                        if let Some(pos) = request.windows(4).position(|w| w == b"\r\n\r\n") {
+                            break pos + 4;
+                        }
+                    };
+                    let headers = String::from_utf8_lossy(&request[..header_end]).to_string();
+                    let content_length = headers
+                        .lines()
+                        .find_map(|line| {
+                            let (name, value) = line.split_once(':')?;
+                            name.eq_ignore_ascii_case("content-length")
+                                .then(|| value.trim().parse::<usize>().ok())
+                                .flatten()
+                        })
+                        .unwrap_or(0);
+                    while request.len() < header_end + content_length {
+                        let n = socket.read(&mut buf).await.unwrap();
+                        if n == 0 {
+                            return;
+                        }
+                        request.extend_from_slice(&buf[..n]);
+                    }
+                    let body = &request[header_end..header_end + content_length];
+                    let session_header = headers.lines().find_map(|line| {
+                        let (name, value) = line.split_once(':')?;
+                        name.eq_ignore_ascii_case("mcp-session-id")
+                            .then(|| value.trim().to_string())
+                    });
+
+                    if headers.starts_with("GET /mcp ") {
+                        let count = get_count.fetch_add(1, AtomicOrdering::SeqCst);
+                        let session = if count == 0 { "sess-old" } else { "sess-new" };
+                        let response = format!(
+                            "HTTP/1.1 200 OK\r\nMcp-Session-Id: {session}\r\nContent-Length: 0\r\n\r\n"
+                        );
+                        socket.write_all(response.as_bytes()).await.unwrap();
+                        return;
+                    }
+
+                    let request_json: serde_json::Value = serde_json::from_slice(body).unwrap();
+                    let method = request_json
+                        .get("method")
+                        .and_then(serde_json::Value::as_str)
+                        .unwrap_or("");
+                    let id = request_json
+                        .get("id")
+                        .cloned()
+                        .unwrap_or_else(|| serde_json::json!("0"));
+
+                    if method == "tools/call" && session_header.as_deref() == Some("sess-old") {
+                        stale_seen.store(true, AtomicOrdering::SeqCst);
+                        socket
+                            .write_all(
+                                b"HTTP/1.1 404 Not Found\r\nContent-Type: application/json\r\nContent-Length: 27\r\n\r\n{\"error\":\"session expired\"}",
+                            )
+                            .await
+                            .unwrap();
+                        return;
+                    }
+
+                    let result = match method {
+                        "initialize" => serde_json::json!({
+                            "protocolVersion": "2024-11-05",
+                            "capabilities": {}
+                        }),
+                        "tools/list" => serde_json::json!({
+                            "tools": [
+                                { "name": "search", "inputSchema": {} }
+                            ]
+                        }),
+                        "resources/list" => serde_json::json!({ "resources": [] }),
+                        "resources/templates/list" => {
+                            serde_json::json!({ "resourceTemplates": [] })
+                        }
+                        "prompts/list" => serde_json::json!({ "prompts": [] }),
+                        "tools/call" => {
+                            assert_eq!(session_header.as_deref(), Some("sess-new"));
+                            success_seen.store(true, AtomicOrdering::SeqCst);
+                            serde_json::json!({ "content": [{ "type": "text", "text": "ok" }] })
+                        }
+                        _ => {
+                            socket
+                                .write_all(b"HTTP/1.1 202 Accepted\r\nContent-Length: 0\r\n\r\n")
+                                .await
+                                .unwrap();
+                            return;
+                        }
+                    };
+                    let response_body = serde_json::json!({
+                        "jsonrpc": "2.0",
+                        "id": id,
+                        "result": result
+                    })
+                    .to_string();
+                    let response = format!(
+                        "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n{}",
+                        response_body.len(),
+                        response_body
+                    );
+                    socket.write_all(response.as_bytes()).await.unwrap();
+                });
+            }
+        });
+
+        let mut cfg = McpConfig::default();
+        cfg.servers.insert(
+            "dephy".to_string(),
+            McpServerConfig {
+                command: None,
+                args: Vec::new(),
+                env: HashMap::new(),
+                url: Some(format!("http://{addr}/mcp")),
+                transport: None,
+                connect_timeout: Some(2),
+                execute_timeout: Some(2),
+                read_timeout: None,
+                disabled: false,
+                enabled: true,
+                required: false,
+                enabled_tools: Vec::new(),
+                disabled_tools: Vec::new(),
+                headers: HashMap::new(),
+            },
+        );
+        let mut pool = McpPool::new(cfg);
+
+        let result = pool
+            .call_tool("mcp_dephy_search", serde_json::json!({ "query": "dephy" }))
+            .await
+            .unwrap();
+
+        assert_eq!(
+            result,
+            serde_json::json!({ "content": [{ "type": "text", "text": "ok" }] })
+        );
+        assert!(stale_seen.load(AtomicOrdering::SeqCst));
+        assert!(success_seen.load(AtomicOrdering::SeqCst));
+        assert_eq!(get_count.load(AtomicOrdering::SeqCst), 2);
+
+        server.abort();
+    }
+
+    #[tokio::test]
+    async fn legacy_sse_session_expiry_is_marked_stale() {
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::TcpListener;
+        use tokio::sync::mpsc;
+
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+
+        let server = tokio::spawn(async move {
+            let (mut socket, _) = listener.accept().await.unwrap();
+            let mut request = Vec::new();
+            let mut buf = [0; 4096];
+            let header_end = loop {
+                let n = socket.read(&mut buf).await.unwrap();
+                if n == 0 {
+                    return;
+                }
+                request.extend_from_slice(&buf[..n]);
+                if let Some(pos) = request.windows(4).position(|w| w == b"\r\n\r\n") {
+                    break pos + 4;
+                }
+            };
+            let headers = String::from_utf8_lossy(&request[..header_end]);
+            assert!(headers.starts_with("POST /messages "));
+            socket
+                .write_all(
+                    b"HTTP/1.1 400 Bad Request\r\nContent-Type: application/json\r\nContent-Length: 27\r\n\r\n{\"error\":\"session expired\"}",
+                )
+                .await
+                .unwrap();
+        });
+
+        let (_sender, receiver) = mpsc::unbounded_channel();
+        let mut transport = SseTransport {
+            client: reqwest::Client::new(),
+            base_url: format!("http://{addr}/sse"),
+            headers: HashMap::new(),
+            endpoint_url: Some(format!("http://{addr}/messages")),
+            receiver,
+            pending_messages: VecDeque::new(),
+        };
+
+        let err = transport
+            .send(br#"{"jsonrpc":"2.0","id":1,"method":"tools/call"}"#.to_vec())
+            .await
+            .expect_err("expired SSE session should fail");
+
+        assert!(
+            is_mcp_stale_session_error(&err),
+            "SSE session expiry should be retryable, got: {err:#}"
+        );
+
+        server.abort();
+    }
+
+    #[tokio::test]
+    async fn legacy_sse_closed_stream_reconnects_and_retries_tool_call() {
+        use std::sync::atomic::{AtomicUsize, Ordering as AtomicOrdering};
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::{TcpListener, TcpStream};
+        use tokio::sync::mpsc;
+
+        async fn read_http_request(socket: &mut TcpStream) -> (String, serde_json::Value) {
+            let mut request = Vec::new();
+            let mut buf = [0; 4096];
+            let header_end = loop {
+                let n = socket.read(&mut buf).await.unwrap();
+                if n == 0 {
+                    return (String::new(), serde_json::Value::Null);
+                }
+                request.extend_from_slice(&buf[..n]);
+                if let Some(pos) = request.windows(4).position(|w| w == b"\r\n\r\n") {
+                    break pos + 4;
+                }
+            };
+            let headers = String::from_utf8_lossy(&request[..header_end]).to_string();
+            let content_length = headers
+                .lines()
+                .find_map(|line| {
+                    let (name, value) = line.split_once(':')?;
+                    name.eq_ignore_ascii_case("content-length")
+                        .then(|| value.trim().parse::<usize>().ok())
+                        .flatten()
+                })
+                .unwrap_or(0);
+            while request.len() < header_end + content_length {
+                let n = socket.read(&mut buf).await.unwrap();
+                if n == 0 {
+                    return (headers, serde_json::Value::Null);
+                }
+                request.extend_from_slice(&buf[..n]);
+            }
+            let body = &request[header_end..header_end + content_length];
+            let json = if body.is_empty() {
+                serde_json::Value::Null
+            } else {
+                serde_json::from_slice(body).unwrap()
+            };
+            (headers, json)
+        }
+
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let active_sse = Arc::new(Mutex::new(None::<mpsc::UnboundedSender<Option<String>>>));
+        let get_count = Arc::new(AtomicUsize::new(0));
+        let tool_call_count = Arc::new(AtomicUsize::new(0));
+        let success_seen = Arc::new(AtomicBool::new(false));
+        let server_active_sse = Arc::clone(&active_sse);
+        let server_get_count = Arc::clone(&get_count);
+        let server_tool_call_count = Arc::clone(&tool_call_count);
+        let server_success_seen = Arc::clone(&success_seen);
+
+        let server = tokio::spawn(async move {
+            loop {
+                let Ok((mut socket, _)) = listener.accept().await else {
+                    break;
+                };
+                let active_sse = Arc::clone(&server_active_sse);
+                let get_count = Arc::clone(&server_get_count);
+                let tool_call_count = Arc::clone(&server_tool_call_count);
+                let success_seen = Arc::clone(&server_success_seen);
+                tokio::spawn(async move {
+                    let (headers, request_json) = read_http_request(&mut socket).await;
+                    if headers.starts_with("GET /sse ") {
+                        get_count.fetch_add(1, AtomicOrdering::SeqCst);
+                        let (tx, mut rx) = mpsc::unbounded_channel::<Option<String>>();
+                        *active_sse.lock().unwrap() = Some(tx);
+                        socket
+                            .write_all(
+                                b"HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\n\r\n",
+                            )
+                            .await
+                            .unwrap();
+                        socket
+                            .write_all(b"event: endpoint\ndata: /messages\n\n")
+                            .await
+                            .unwrap();
+                        while let Some(message) = rx.recv().await {
+                            let Some(message) = message else {
+                                return;
+                            };
+                            let event = format!("event: message\ndata: {message}\n\n");
+                            socket.write_all(event.as_bytes()).await.unwrap();
+                        }
+                        return;
+                    }
+
+                    if !headers.starts_with("POST /messages ") {
+                        return;
+                    }
+
+                    socket
+                        .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n")
+                        .await
+                        .unwrap();
+
+                    let method = request_json
+                        .get("method")
+                        .and_then(serde_json::Value::as_str)
+                        .unwrap_or("");
+                    if method == "notifications/initialized" {
+                        return;
+                    }
+
+                    let id = request_json
+                        .get("id")
+                        .cloned()
+                        .unwrap_or_else(|| serde_json::json!("0"));
+
+                    if method == "tools/call" {
+                        let count = tool_call_count.fetch_add(1, AtomicOrdering::SeqCst);
+                        if count == 0 {
+                            if let Some(tx) = active_sse.lock().unwrap().take() {
+                                let _ = tx.send(None);
+                            }
+                            return;
+                        }
+                    }
+
+                    let result = match method {
+                        "initialize" => serde_json::json!({
+                            "protocolVersion": "2024-11-05",
+                            "capabilities": {}
+                        }),
+                        "tools/list" => serde_json::json!({
+                            "tools": [
+                                { "name": "search", "inputSchema": {} }
+                            ]
+                        }),
+                        "resources/list" => serde_json::json!({ "resources": [] }),
+                        "resources/templates/list" => {
+                            serde_json::json!({ "resourceTemplates": [] })
+                        }
+                        "prompts/list" => serde_json::json!({ "prompts": [] }),
+                        "tools/call" => {
+                            success_seen.store(true, AtomicOrdering::SeqCst);
+                            serde_json::json!({ "content": [{ "type": "text", "text": "ok" }] })
+                        }
+                        other => panic!("unexpected method: {other}"),
+                    };
+                    let response = serde_json::json!({
+                        "jsonrpc": "2.0",
+                        "id": id,
+                        "result": result
+                    })
+                    .to_string();
+                    if let Some(tx) = active_sse.lock().unwrap().as_ref() {
+                        let _ = tx.send(Some(response));
+                    }
+                });
+            }
+        });
+
+        let mut cfg = McpConfig::default();
+        cfg.servers.insert(
+            "dephy".to_string(),
+            McpServerConfig {
+                command: None,
+                args: Vec::new(),
+                env: HashMap::new(),
+                url: Some(format!("http://{addr}/sse")),
+                transport: Some("sse".to_string()),
+                connect_timeout: Some(2),
+                execute_timeout: Some(2),
+                read_timeout: None,
+                disabled: false,
+                enabled: true,
+                required: false,
+                enabled_tools: Vec::new(),
+                disabled_tools: Vec::new(),
+                headers: HashMap::new(),
+            },
+        );
+        let mut pool = McpPool::new(cfg);
+
+        let result = pool
+            .call_tool("mcp_dephy_search", serde_json::json!({ "query": "dephy" }))
+            .await
+            .unwrap();
+
+        assert_eq!(
+            result,
+            serde_json::json!({ "content": [{ "type": "text", "text": "ok" }] })
+        );
+        assert_eq!(tool_call_count.load(AtomicOrdering::SeqCst), 2);
+        assert_eq!(get_count.load(AtomicOrdering::SeqCst), 2);
+        assert!(success_seen.load(AtomicOrdering::SeqCst));
+
+        server.abort();
+    }
+
     #[test]
     fn session_id_starts_none() {
         let transport = StreamableHttpTransport::new(
diff --git a/crates/tui/src/models.rs b/crates/tui/src/models.rs
index a5f52c6d..91c642e1 100644
--- a/crates/tui/src/models.rs
+++ b/crates/tui/src/models.rs
@@ -208,16 +208,22 @@ pub struct Usage {
 }
 
 /// Map known models to their approximate context window sizes.
+///
+/// Lookup order:
+/// 1. An explicit `_Nk` suffix in the model name, for **any** vendor. This
+///    lets self-hosted deployments advertise their window through the served
+///    model name (e.g. a vLLM `--served-model-name qwen3-32b-256k`), which is
+///    the only signal we have for non-DeepSeek/Claude models. The 1000-token
+///    approximation is fine for compaction-threshold math.
+/// 2. DeepSeek vendor heuristics (V4 family -> 1M, legacy -> 128K).
+/// 3. Claude -> 200K.
 #[must_use]
 pub fn context_window_for_model(model: &str) -> Option<u32> {
     let lower = model.to_lowercase();
-    // Unknown legacy DeepSeek model IDs default to 128K unless an explicit
-    // *k suffix is present. DeepSeek-V4 family and current compatibility
-    // aliases ship with a 1M context window.
+    if let Some(explicit_window) = explicit_context_window_hint(&lower) {
+        return Some(explicit_window);
+    }
     if lower.contains("deepseek") {
-        if let Some(explicit_window) = deepseek_context_window_hint(&lower) {
-            return Some(explicit_window);
-        }
         if lower.contains("v4") {
             return Some(DEEPSEEK_V4_CONTEXT_WINDOW_TOKENS);
         }
@@ -229,7 +235,9 @@ pub fn context_window_for_model(model: &str) -> Option<u32> {
     None
 }
 
-fn deepseek_context_window_hint(model_lower: &str) -> Option<u32> {
+/// Parse an explicit `_Nk` context-window hint from a model name (vendor
+/// agnostic). Returns the window in tokens for `N` in `8..=1024`.
+fn explicit_context_window_hint(model_lower: &str) -> Option<u32> {
     let bytes = model_lower.as_bytes();
     let mut i = 0usize;
     while i < bytes.len() {
diff --git a/crates/tui/src/network_policy.rs b/crates/tui/src/network_policy.rs
index ba2332df..a36ef2e9 100644
--- a/crates/tui/src/network_policy.rs
+++ b/crates/tui/src/network_policy.rs
@@ -46,6 +46,7 @@
 
 use std::fs::{self, OpenOptions};
 use std::io::Write;
+use std::net::{IpAddr, Ipv4Addr};
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
 
@@ -265,6 +266,27 @@ fn host_matches(entry: &str, normalized_host: &str) -> bool {
     }
 }
 
+/// Parse an IPv4 CIDR string such as `"198.18.0.0/15"` into `(base, prefix)`.
+/// Returns `None` for malformed input or a prefix length above 32.
+fn parse_ipv4_cidr(cidr: &str) -> Option<(Ipv4Addr, u8)> {
+    let (addr, prefix) = cidr.split_once('/')?;
+    let base: Ipv4Addr = addr.trim().parse().ok()?;
+    let prefix: u8 = prefix.trim().parse().ok()?;
+    if prefix > 32 {
+        return None;
+    }
+    Some((base, prefix))
+}
+
+/// Whether `ip` is contained in the `base/prefix` IPv4 CIDR block.
+fn ipv4_in_cidr(ip: Ipv4Addr, base: Ipv4Addr, prefix: u8) -> bool {
+    if prefix == 0 {
+        return true;
+    }
+    let mask: u32 = u32::MAX << (32 - prefix);
+    (u32::from(ip) & mask) == (u32::from(base) & mask)
+}
+
 /// Best-effort writer for the network audit log.
 #[derive(Debug, Clone)]
 pub struct NetworkAuditor {
@@ -415,6 +437,12 @@ pub struct NetworkPolicyDecider {
     policy: NetworkPolicy,
     cache: NetworkSessionCache,
     auditor: Option<NetworkAuditor>,
+    /// IPv4 CIDR ranges that are treated as benign fake-IP placeholders (e.g.
+    /// a transparent-proxy / TUN setup running in `fake-ip` mode, where DNS
+    /// resolves every hostname into a reserved range like `198.18.0.0/15`).
+    /// A resolved IP inside one of these ranges bypasses the restricted-IP SSRF
+    /// block; real private/loopback/link-local/metadata IPs are unaffected.
+    trusted_fakeip_cidrs: Vec<(Ipv4Addr, u8)>,
 }
 
 impl NetworkPolicyDecider {
@@ -425,6 +453,38 @@ impl NetworkPolicyDecider {
             policy,
             cache: NetworkSessionCache::new(),
             auditor,
+            trusted_fakeip_cidrs: Vec::new(),
+        }
+    }
+
+    /// Register IPv4 CIDR ranges to treat as benign fake-IP placeholders.
+    /// Invalid CIDR strings are skipped. See [`Self::is_trusted_fakeip_addr`].
+    #[must_use]
+    pub fn with_trusted_fakeip_cidrs(mut self, cidrs: &[&str]) -> Self {
+        for cidr in cidrs {
+            if let Some(parsed) = parse_ipv4_cidr(cidr) {
+                self.trusted_fakeip_cidrs.push(parsed);
+            }
+        }
+        self
+    }
+
+    /// Whether `ip` falls inside a configured fake-IP placeholder range.
+    ///
+    /// In `fake-ip` proxy/TUN setups the local resolver maps every hostname to
+    /// a reserved range (commonly `198.18.0.0/15`), so the DNS-resolution SSRF
+    /// check would otherwise reject every request. This narrowly trusts only
+    /// those placeholder addresses — real private/loopback/link-local/cloud-
+    /// metadata IPs are *not* matched and stay blocked.
+    #[must_use]
+    pub fn is_trusted_fakeip_addr(&self, ip: &IpAddr) -> bool {
+        match ip {
+            IpAddr::V4(v4) => self
+                .trusted_fakeip_cidrs
+                .iter()
+                .any(|(base, prefix)| ipv4_in_cidr(*v4, *base, *prefix)),
+            // fake-ip placeholders are IPv4-only in practice.
+            IpAddr::V6(_) => false,
         }
     }
 
@@ -643,6 +703,30 @@ mod tests {
         assert!(p.trusts_proxy_fakeip_host("avatars.githubusercontent.com"));
     }
 
+    #[test]
+    fn trusted_fakeip_cidr_allows_placeholder_but_not_real_private() {
+        let decider = NetworkPolicyDecider::new(NetworkPolicy::default(), None)
+            .with_trusted_fakeip_cidrs(&["198.18.0.0/15"]);
+
+        // fake-ip placeholder range (clash default / IETF benchmark) is trusted
+        assert!(decider.is_trusted_fakeip_addr(&"198.18.0.5".parse::<std::net::IpAddr>().unwrap()));
+        assert!(
+            decider.is_trusted_fakeip_addr(&"198.19.255.255".parse::<std::net::IpAddr>().unwrap())
+        );
+
+        // real private / loopback / link-local / cloud-metadata are NOT trusted
+        for ip in ["192.168.1.1", "10.0.0.1", "127.0.0.1", "169.254.169.254"] {
+            assert!(
+                !decider.is_trusted_fakeip_addr(&ip.parse::<std::net::IpAddr>().unwrap()),
+                "{ip} must not be treated as a fake-ip placeholder"
+            );
+        }
+
+        // no ranges configured → nothing trusted
+        let bare = NetworkPolicyDecider::new(NetworkPolicy::default(), None);
+        assert!(!bare.is_trusted_fakeip_addr(&"198.18.0.5".parse::<std::net::IpAddr>().unwrap()));
+    }
+
     #[test]
     fn host_from_url_extracts_host() {
         assert_eq!(
diff --git a/crates/tui/src/palette.rs b/crates/tui/src/palette.rs
index c9980200..fb1c66e8 100644
--- a/crates/tui/src/palette.rs
+++ b/crates/tui/src/palette.rs
@@ -4,15 +4,57 @@ use ratatui::style::Color;
 #[cfg(target_os = "macos")]
 use std::process::Command;
 
-pub const DEEPSEEK_BLUE_RGB: (u8, u8, u8) = (53, 120, 229); // #3578E5
-pub const DEEPSEEK_SKY_RGB: (u8, u8, u8) = (106, 174, 242);
+// v0.8.46 Whale dark palette — improved contrast and layer separation.
+pub const WHALE_BG_RGB: (u8, u8, u8) = (10, 17, 32); // #0A1120 Deep Navy
+pub const WHALE_PANEL_RGB: (u8, u8, u8) = (22, 34, 56); // #162238
+pub const WHALE_ELEVATED_RGB: (u8, u8, u8) = (36, 52, 78); // #24344E
+pub const WHALE_SELECTION_RGB: (u8, u8, u8) = (40, 56, 84); // #283854 — darker to avoid bright pop on deep navy
+pub const WHALE_TEXT_BODY_RGB: (u8, u8, u8) = (246, 242, 232); // #F6F2E8 Whale Ivory
+pub const WHALE_TEXT_SOFT_RGB: (u8, u8, u8) = (217, 224, 234); // #D9E0EA
+pub const WHALE_TEXT_MUTED_RGB: (u8, u8, u8) = (169, 180, 199); // #A9B4C7 Mist Gray
+pub const WHALE_TEXT_HINT_RGB: (u8, u8, u8) = (138, 150, 174); // #8A96AE
+#[allow(dead_code)]
+pub const WHALE_TEXT_DIM_RGB: (u8, u8, u8) = (118, 130, 156); // #76829C
+pub const WHALE_ACCENT_PRIMARY_RGB: (u8, u8, u8) = (246, 196, 83); // #F6C453 Signal Gold
+pub const WHALE_ACCENT_SECONDARY_RGB: (u8, u8, u8) = (79, 209, 197); // #4FD1C5 Seafoam
+pub const WHALE_ACCENT_ACTION_RGB: (u8, u8, u8) = (255, 122, 89); // #FF7A59 Coral Spark
+pub const WHALE_ERROR_RGB: (u8, u8, u8) = (255, 92, 122); // #FF5C7A Rose Red
+pub const WHALE_ERROR_HOVER_RGB: (u8, u8, u8) = (255, 120, 144); // #FF7890 Rose Hover
+pub const WHALE_ERROR_SURFACE_RGB: (u8, u8, u8) = (42, 18, 26); // #2A121A Error Surface
+pub const WHALE_ERROR_BORDER_RGB: (u8, u8, u8) = (255, 138, 160); // #FF8AA0 Error Border
+pub const WHALE_ERROR_TEXT_RGB: (u8, u8, u8) = (255, 214, 222); // #FFD6DE Error Text
+pub const WHALE_WARNING_RGB: (u8, u8, u8) = (240, 160, 48); // #F0A030
+pub const WHALE_SUCCESS_RGB: (u8, u8, u8) = (79, 209, 197); // #4FD1C5 Seafoam
+pub const WHALE_INFO_RGB: (u8, u8, u8) = (106, 174, 242); // #6AAEF2 Sky
+pub const WHALE_BORDER_RGB: (u8, u8, u8) = (52, 88, 145); // #345891
+pub const WHALE_REASONING_TEXT_RGB: (u8, u8, u8) = (224, 153, 72); // #E09948
+pub const WHALE_REASONING_SURFACE_RGB: (u8, u8, u8) = (42, 34, 24); // #2A2218
+pub const WHALE_REASONING_TINT_RGB: (u8, u8, u8) = (24, 36, 52); // #182434
+pub const WHALE_DIFF_ADDED_RGB: (u8, u8, u8) = (87, 199, 133); // #57C785
+#[allow(dead_code)]
+pub const WHALE_DIFF_DELETED_RGB: (u8, u8, u8) = (255, 92, 122); // #FF5C7A Rose Red
+pub const WHALE_DIFF_ADDED_BG_RGB: (u8, u8, u8) = (18, 42, 34); // #122A22
+pub const WHALE_DIFF_DELETED_BG_RGB: (u8, u8, u8) = (42, 18, 26); // #2A121A
+pub const WHALE_MODE_AGENT_RGB: (u8, u8, u8) = (80, 150, 255); // #5096FF
+pub const WHALE_MODE_YOLO_RGB: (u8, u8, u8) = (255, 100, 100); // #FF6464
+pub const WHALE_MODE_PLAN_RGB: (u8, u8, u8) = (246, 196, 83); // #F6C453 Signal Gold
+pub const WHALE_MODE_GOAL_RGB: (u8, u8, u8) = (100, 220, 160); // #64DCA0
+pub const WHALE_TOOL_LIVE_RGB: (u8, u8, u8) = (140, 190, 238); // #8CBEEE
+pub const WHALE_TOOL_ISSUE_RGB: (u8, u8, u8) = (198, 150, 160); // #C696A0
+pub const WHALE_TOOL_OUTPUT_RGB: (u8, u8, u8) = (194, 208, 224); // #C2D0E0
+pub const WHALE_TOOL_SURFACE_RGB: (u8, u8, u8) = (28, 40, 62); // #1C283E
+pub const WHALE_TOOL_ACTIVE_RGB: (u8, u8, u8) = (38, 54, 80); // #263650
+
+// Backward-compatible aliases for existing call sites.
+pub const DEEPSEEK_BLUE_RGB: (u8, u8, u8) = WHALE_ACCENT_PRIMARY_RGB;
+pub const DEEPSEEK_SKY_RGB: (u8, u8, u8) = WHALE_INFO_RGB;
 #[allow(dead_code)]
 pub const DEEPSEEK_AQUA_RGB: (u8, u8, u8) = (54, 187, 212);
 #[allow(dead_code)]
 pub const DEEPSEEK_NAVY_RGB: (u8, u8, u8) = (24, 63, 138);
-pub const DEEPSEEK_INK_RGB: (u8, u8, u8) = (11, 21, 38);
-pub const DEEPSEEK_SLATE_RGB: (u8, u8, u8) = (18, 28, 46);
-pub const DEEPSEEK_RED_RGB: (u8, u8, u8) = (226, 80, 96);
+pub const DEEPSEEK_INK_RGB: (u8, u8, u8) = WHALE_BG_RGB;
+pub const DEEPSEEK_SLATE_RGB: (u8, u8, u8) = WHALE_PANEL_RGB;
+pub const DEEPSEEK_RED_RGB: (u8, u8, u8) = WHALE_ERROR_RGB;
 
 pub const LIGHT_SURFACE_RGB: (u8, u8, u8) = (246, 248, 251); // #F6F8FB
 pub const LIGHT_PANEL_RGB: (u8, u8, u8) = (236, 242, 248); // #ECF2F8
@@ -40,13 +82,14 @@ pub const GRAYSCALE_BORDER_RGB: (u8, u8, u8) = (96, 96, 96); // #606060
 pub const GRAYSCALE_SELECTION_RGB: (u8, u8, u8) = (62, 62, 62); // #3E3E3E
 
 // New semantic colors
-pub const BORDER_COLOR_RGB: (u8, u8, u8) = (42, 74, 127); // #2A4A7F
+pub const BORDER_COLOR_RGB: (u8, u8, u8) = WHALE_BORDER_RGB; // #2A4A7F
 
 pub const DEEPSEEK_BLUE: Color = Color::Rgb(
     DEEPSEEK_BLUE_RGB.0,
     DEEPSEEK_BLUE_RGB.1,
     DEEPSEEK_BLUE_RGB.2,
 );
+/// Now maps to the secondary accent (Seafoam) for backward compat.
 pub const DEEPSEEK_SKY: Color =
     Color::Rgb(DEEPSEEK_SKY_RGB.0, DEEPSEEK_SKY_RGB.1, DEEPSEEK_SKY_RGB.2);
 #[allow(dead_code)]
@@ -181,13 +224,41 @@ pub const GRAYSCALE_SELECTION_BG: Color = Color::Rgb(
     GRAYSCALE_SELECTION_RGB.2,
 );
 
-pub const TEXT_BODY: Color = Color::Rgb(226, 232, 240); // #E2E8F0
-pub const TEXT_SECONDARY: Color = Color::Rgb(177, 190, 207); // #B1BECF
-pub const TEXT_HINT: Color = Color::Rgb(135, 151, 171); // #8797AB
-pub const TEXT_ACCENT: Color = DEEPSEEK_SKY;
-pub const SELECTION_TEXT: Color = Color::White;
-pub const TEXT_SOFT: Color = Color::Rgb(217, 226, 238); // #D9E2EE
-pub const TEXT_REASONING: Color = Color::Rgb(211, 170, 112); // #D3AA70
+pub const TEXT_BODY: Color = Color::Rgb(
+    WHALE_TEXT_BODY_RGB.0,
+    WHALE_TEXT_BODY_RGB.1,
+    WHALE_TEXT_BODY_RGB.2,
+);
+pub const TEXT_SECONDARY: Color = Color::Rgb(
+    WHALE_TEXT_MUTED_RGB.0,
+    WHALE_TEXT_MUTED_RGB.1,
+    WHALE_TEXT_MUTED_RGB.2,
+);
+pub const TEXT_HINT: Color = Color::Rgb(
+    WHALE_TEXT_HINT_RGB.0,
+    WHALE_TEXT_HINT_RGB.1,
+    WHALE_TEXT_HINT_RGB.2,
+);
+pub const TEXT_ACCENT: Color = Color::Rgb(
+    WHALE_ACCENT_SECONDARY_RGB.0,
+    WHALE_ACCENT_SECONDARY_RGB.1,
+    WHALE_ACCENT_SECONDARY_RGB.2,
+);
+pub const SELECTION_TEXT: Color = Color::Rgb(
+    WHALE_TEXT_BODY_RGB.0,
+    WHALE_TEXT_BODY_RGB.1,
+    WHALE_TEXT_BODY_RGB.2,
+); // Ivory — softer than pure white
+pub const TEXT_SOFT: Color = Color::Rgb(
+    WHALE_TEXT_SOFT_RGB.0,
+    WHALE_TEXT_SOFT_RGB.1,
+    WHALE_TEXT_SOFT_RGB.2,
+);
+pub const TEXT_REASONING: Color = Color::Rgb(
+    WHALE_REASONING_TEXT_RGB.0,
+    WHALE_REASONING_TEXT_RGB.1,
+    WHALE_REASONING_TEXT_RGB.2,
+);
 
 // Compatibility aliases for existing call sites.
 pub const TEXT_PRIMARY: Color = TEXT_BODY;
@@ -200,51 +271,140 @@ pub const LIGHT_USER_BODY: Color = Color::Rgb(21, 128, 61); // #15803D green
 pub const BORDER_COLOR: Color =
     Color::Rgb(BORDER_COLOR_RGB.0, BORDER_COLOR_RGB.1, BORDER_COLOR_RGB.2);
 #[allow(dead_code)]
-pub const ACCENT_PRIMARY: Color = DEEPSEEK_BLUE; // #3578E5
+pub const ACCENT_PRIMARY: Color = Color::Rgb(
+    WHALE_ACCENT_PRIMARY_RGB.0,
+    WHALE_ACCENT_PRIMARY_RGB.1,
+    WHALE_ACCENT_PRIMARY_RGB.2,
+);
 #[allow(dead_code)]
-pub const ACCENT_SECONDARY: Color = TEXT_ACCENT; // #6AAEF2
+pub const ACCENT_SECONDARY: Color = Color::Rgb(
+    WHALE_ACCENT_SECONDARY_RGB.0,
+    WHALE_ACCENT_SECONDARY_RGB.1,
+    WHALE_ACCENT_SECONDARY_RGB.2,
+);
 #[allow(dead_code)]
-pub const BACKGROUND_DARK: Color = Color::Rgb(13, 26, 48); // #0D1A30
+pub const BACKGROUND_DARK: Color = Color::Rgb(WHALE_BG_RGB.0, WHALE_BG_RGB.1, WHALE_BG_RGB.2);
 #[allow(dead_code)]
-pub const STATUS_NEUTRAL: Color = Color::Rgb(160, 160, 160); // #A0A0A0
+pub const STATUS_NEUTRAL: Color = TEXT_MUTED;
 #[allow(dead_code)]
-pub const SURFACE_PANEL: Color = Color::Rgb(21, 33, 52); // #152134
+pub const SURFACE_PANEL: Color =
+    Color::Rgb(WHALE_PANEL_RGB.0, WHALE_PANEL_RGB.1, WHALE_PANEL_RGB.2);
 #[allow(dead_code)]
-pub const SURFACE_ELEVATED: Color = Color::Rgb(28, 42, 64); // #1C2A40
-pub const SURFACE_REASONING: Color = Color::Rgb(54, 44, 26); // #362C1A
-pub const SURFACE_REASONING_TINT: Color = Color::Rgb(16, 24, 37); // #101825
+pub const SURFACE_ELEVATED: Color = Color::Rgb(
+    WHALE_ELEVATED_RGB.0,
+    WHALE_ELEVATED_RGB.1,
+    WHALE_ELEVATED_RGB.2,
+);
+pub const SURFACE_REASONING: Color = Color::Rgb(
+    WHALE_REASONING_SURFACE_RGB.0,
+    WHALE_REASONING_SURFACE_RGB.1,
+    WHALE_REASONING_SURFACE_RGB.2,
+);
+pub const SURFACE_REASONING_TINT: Color = Color::Rgb(
+    WHALE_REASONING_TINT_RGB.0,
+    WHALE_REASONING_TINT_RGB.1,
+    WHALE_REASONING_TINT_RGB.2,
+);
 #[allow(dead_code)]
-pub const SURFACE_REASONING_ACTIVE: Color = Color::Rgb(68, 53, 28); // #44351C
+pub const SURFACE_REASONING_ACTIVE: Color = Color::Rgb(58, 46, 32);
 #[allow(dead_code)]
-pub const SURFACE_TOOL: Color = Color::Rgb(24, 39, 60); // #18273C
+pub const SURFACE_TOOL: Color = Color::Rgb(
+    WHALE_TOOL_SURFACE_RGB.0,
+    WHALE_TOOL_SURFACE_RGB.1,
+    WHALE_TOOL_SURFACE_RGB.2,
+);
 #[allow(dead_code)]
-pub const SURFACE_TOOL_ACTIVE: Color = Color::Rgb(29, 48, 73); // #1D3049
+pub const SURFACE_TOOL_ACTIVE: Color = Color::Rgb(
+    WHALE_TOOL_ACTIVE_RGB.0,
+    WHALE_TOOL_ACTIVE_RGB.1,
+    WHALE_TOOL_ACTIVE_RGB.2,
+);
 #[allow(dead_code)]
-pub const SURFACE_SUCCESS: Color = Color::Rgb(22, 56, 63); // #16383F
+pub const SURFACE_SUCCESS: Color = Color::Rgb(18, 42, 37); // dark teal tint
 #[allow(dead_code)]
-pub const SURFACE_ERROR: Color = Color::Rgb(63, 27, 36); // #3F1B24
-pub const DIFF_ADDED_BG: Color = Color::Rgb(18, 52, 38); // #123426 dark green tint
-pub const DIFF_DELETED_BG: Color = Color::Rgb(52, 22, 28); // #34161C dark red tint
-pub const DIFF_ADDED: Color = Color::Rgb(87, 199, 133); // #57C785
-pub const ACCENT_REASONING_LIVE: Color = Color::Rgb(224, 153, 72); // #E09948
-pub const ACCENT_TOOL_LIVE: Color = Color::Rgb(133, 184, 234); // #85B8EA
-pub const ACCENT_TOOL_ISSUE: Color = Color::Rgb(192, 143, 153); // #C08F99
-pub const TEXT_TOOL_OUTPUT: Color = Color::Rgb(191, 205, 220); // #BFCEDC
+pub const SURFACE_ERROR: Color = Color::Rgb(
+    WHALE_ERROR_SURFACE_RGB.0,
+    WHALE_ERROR_SURFACE_RGB.1,
+    WHALE_ERROR_SURFACE_RGB.2,
+);
+pub const DIFF_ADDED_BG: Color = Color::Rgb(
+    WHALE_DIFF_ADDED_BG_RGB.0,
+    WHALE_DIFF_ADDED_BG_RGB.1,
+    WHALE_DIFF_ADDED_BG_RGB.2,
+);
+pub const DIFF_DELETED_BG: Color = Color::Rgb(
+    WHALE_DIFF_DELETED_BG_RGB.0,
+    WHALE_DIFF_DELETED_BG_RGB.1,
+    WHALE_DIFF_DELETED_BG_RGB.2,
+);
+pub const DIFF_ADDED: Color = Color::Rgb(
+    WHALE_DIFF_ADDED_RGB.0,
+    WHALE_DIFF_ADDED_RGB.1,
+    WHALE_DIFF_ADDED_RGB.2,
+);
+pub const ACCENT_REASONING_LIVE: Color = Color::Rgb(
+    WHALE_REASONING_TEXT_RGB.0,
+    WHALE_REASONING_TEXT_RGB.1,
+    WHALE_REASONING_TEXT_RGB.2,
+);
+pub const ACCENT_TOOL_LIVE: Color = Color::Rgb(
+    WHALE_TOOL_LIVE_RGB.0,
+    WHALE_TOOL_LIVE_RGB.1,
+    WHALE_TOOL_LIVE_RGB.2,
+);
+pub const ACCENT_TOOL_ISSUE: Color = Color::Rgb(
+    WHALE_TOOL_ISSUE_RGB.0,
+    WHALE_TOOL_ISSUE_RGB.1,
+    WHALE_TOOL_ISSUE_RGB.2,
+);
+pub const TEXT_TOOL_OUTPUT: Color = Color::Rgb(
+    WHALE_TOOL_OUTPUT_RGB.0,
+    WHALE_TOOL_OUTPUT_RGB.1,
+    WHALE_TOOL_OUTPUT_RGB.2,
+);
 
 // Legacy status colors - keep for backward compatibility
-pub const STATUS_SUCCESS: Color = DEEPSEEK_SKY;
-pub const STATUS_WARNING: Color = Color::Rgb(255, 170, 60); // Amber
-pub const STATUS_ERROR: Color = DEEPSEEK_RED;
+pub const STATUS_SUCCESS: Color = Color::Rgb(
+    WHALE_SUCCESS_RGB.0,
+    WHALE_SUCCESS_RGB.1,
+    WHALE_SUCCESS_RGB.2,
+);
+pub const STATUS_WARNING: Color = Color::Rgb(
+    WHALE_WARNING_RGB.0,
+    WHALE_WARNING_RGB.1,
+    WHALE_WARNING_RGB.2,
+);
+pub const STATUS_ERROR: Color = Color::Rgb(WHALE_ERROR_RGB.0, WHALE_ERROR_RGB.1, WHALE_ERROR_RGB.2);
 #[allow(dead_code)]
-pub const STATUS_INFO: Color = DEEPSEEK_BLUE;
+pub const STATUS_INFO: Color = Color::Rgb(WHALE_INFO_RGB.0, WHALE_INFO_RGB.1, WHALE_INFO_RGB.2);
 
 // Mode-specific accent colors for mode badges
-pub const MODE_AGENT: Color = Color::Rgb(80, 150, 255); // Bright blue
-pub const MODE_YOLO: Color = Color::Rgb(255, 100, 100); // Warning red
-pub const MODE_PLAN: Color = Color::Rgb(255, 170, 60); // Orange
-pub const MODE_GOAL: Color = Color::Rgb(100, 220, 160); // Mint green
+pub const MODE_AGENT: Color = Color::Rgb(
+    WHALE_MODE_AGENT_RGB.0,
+    WHALE_MODE_AGENT_RGB.1,
+    WHALE_MODE_AGENT_RGB.2,
+);
+pub const MODE_YOLO: Color = Color::Rgb(
+    WHALE_MODE_YOLO_RGB.0,
+    WHALE_MODE_YOLO_RGB.1,
+    WHALE_MODE_YOLO_RGB.2,
+);
+pub const MODE_PLAN: Color = Color::Rgb(
+    WHALE_MODE_PLAN_RGB.0,
+    WHALE_MODE_PLAN_RGB.1,
+    WHALE_MODE_PLAN_RGB.2,
+);
+pub const MODE_GOAL: Color = Color::Rgb(
+    WHALE_MODE_GOAL_RGB.0,
+    WHALE_MODE_GOAL_RGB.1,
+    WHALE_MODE_GOAL_RGB.2,
+);
 
-pub const SELECTION_BG: Color = Color::Rgb(26, 44, 74);
+pub const SELECTION_BG: Color = Color::Rgb(
+    WHALE_SELECTION_RGB.0,
+    WHALE_SELECTION_RGB.1,
+    WHALE_SELECTION_RGB.2,
+);
 #[allow(dead_code)]
 pub const COMPOSER_BG: Color = DEEPSEEK_SLATE;
 
@@ -322,6 +482,7 @@ fn palette_mode_from_apple_interface_style(value: &str) -> PaletteMode {
 pub struct UiTheme {
     pub name: &'static str,
     pub mode: PaletteMode,
+    // Surface hierarchy
     pub surface_bg: Color,
     pub panel_bg: Color,
     pub elevated_bg: Color,
@@ -329,22 +490,45 @@ pub struct UiTheme {
     pub selection_bg: Color,
     pub header_bg: Color,
     pub footer_bg: Color,
-    /// Statusline mode colors (agent/yolo/plan)
-    pub mode_agent: Color,
-    pub mode_yolo: Color,
-    pub mode_plan: Color,
-    pub mode_goal: Color,
-    /// Statusline status colors
-    pub status_ready: Color,
-    pub status_working: Color,
-    pub status_warning: Color,
-    /// Statusline text colors
+    /// Text hierarchy
     pub text_dim: Color,
     pub text_hint: Color,
     pub text_muted: Color,
     pub text_body: Color,
     pub text_soft: Color,
     pub border: Color,
+    // Accent roles
+    pub accent_primary: Color,
+    pub accent_secondary: Color,
+    pub accent_action: Color,
+    // Error / destructive
+    pub error_fg: Color,
+    pub error_hover: Color,
+    pub error_surface: Color,
+    pub error_border: Color,
+    pub error_text: Color,
+    // Status roles (warning / success / info)
+    pub warning: Color,
+    pub success: Color,
+    pub info: Color,
+    // Mode badge colors (agent/yolo/plan/goal)
+    pub mode_agent: Color,
+    pub mode_yolo: Color,
+    pub mode_plan: Color,
+    pub mode_goal: Color,
+    // Footer statusline colors
+    pub status_ready: Color,
+    pub status_working: Color,
+    pub status_warning: Color,
+    // Diff colors
+    pub diff_added_fg: Color,
+    pub diff_deleted_fg: Color,
+    pub diff_added_bg: Color,
+    pub diff_deleted_bg: Color,
+    // Tool cell colors
+    pub tool_running: Color,
+    pub tool_success: Color,
+    pub tool_failed: Color,
 }
 
 pub const UI_THEME: UiTheme = UiTheme {
@@ -357,6 +541,59 @@ pub const UI_THEME: UiTheme = UiTheme {
     selection_bg: SELECTION_BG,
     header_bg: DEEPSEEK_INK,
     footer_bg: DEEPSEEK_INK,
+    text_dim: TEXT_DIM,
+    text_hint: TEXT_HINT,
+    text_muted: TEXT_MUTED,
+    text_body: TEXT_BODY,
+    text_soft: TEXT_SOFT,
+    border: BORDER_COLOR,
+    accent_primary: Color::Rgb(
+        WHALE_ACCENT_PRIMARY_RGB.0,
+        WHALE_ACCENT_PRIMARY_RGB.1,
+        WHALE_ACCENT_PRIMARY_RGB.2,
+    ),
+    accent_secondary: Color::Rgb(
+        WHALE_ACCENT_SECONDARY_RGB.0,
+        WHALE_ACCENT_SECONDARY_RGB.1,
+        WHALE_ACCENT_SECONDARY_RGB.2,
+    ),
+    accent_action: Color::Rgb(
+        WHALE_ACCENT_ACTION_RGB.0,
+        WHALE_ACCENT_ACTION_RGB.1,
+        WHALE_ACCENT_ACTION_RGB.2,
+    ),
+    error_fg: Color::Rgb(WHALE_ERROR_RGB.0, WHALE_ERROR_RGB.1, WHALE_ERROR_RGB.2),
+    error_hover: Color::Rgb(
+        WHALE_ERROR_HOVER_RGB.0,
+        WHALE_ERROR_HOVER_RGB.1,
+        WHALE_ERROR_HOVER_RGB.2,
+    ),
+    error_surface: Color::Rgb(
+        WHALE_ERROR_SURFACE_RGB.0,
+        WHALE_ERROR_SURFACE_RGB.1,
+        WHALE_ERROR_SURFACE_RGB.2,
+    ),
+    error_border: Color::Rgb(
+        WHALE_ERROR_BORDER_RGB.0,
+        WHALE_ERROR_BORDER_RGB.1,
+        WHALE_ERROR_BORDER_RGB.2,
+    ),
+    error_text: Color::Rgb(
+        WHALE_ERROR_TEXT_RGB.0,
+        WHALE_ERROR_TEXT_RGB.1,
+        WHALE_ERROR_TEXT_RGB.2,
+    ),
+    warning: Color::Rgb(
+        WHALE_WARNING_RGB.0,
+        WHALE_WARNING_RGB.1,
+        WHALE_WARNING_RGB.2,
+    ),
+    success: Color::Rgb(
+        WHALE_SUCCESS_RGB.0,
+        WHALE_SUCCESS_RGB.1,
+        WHALE_SUCCESS_RGB.2,
+    ),
+    info: Color::Rgb(WHALE_INFO_RGB.0, WHALE_INFO_RGB.1, WHALE_INFO_RGB.2),
     mode_agent: MODE_AGENT,
     mode_yolo: MODE_YOLO,
     mode_plan: MODE_PLAN,
@@ -364,12 +601,13 @@ pub const UI_THEME: UiTheme = UiTheme {
     status_ready: TEXT_MUTED,
     status_working: DEEPSEEK_SKY,
     status_warning: STATUS_WARNING,
-    text_dim: TEXT_DIM,
-    text_hint: TEXT_HINT,
-    text_muted: TEXT_MUTED,
-    text_body: TEXT_BODY,
-    text_soft: TEXT_SOFT,
-    border: BORDER_COLOR,
+    diff_added_fg: DIFF_ADDED,
+    diff_deleted_fg: Color::Rgb(WHALE_ERROR_RGB.0, WHALE_ERROR_RGB.1, WHALE_ERROR_RGB.2),
+    diff_added_bg: DIFF_ADDED_BG,
+    diff_deleted_bg: DIFF_DELETED_BG,
+    tool_running: ACCENT_TOOL_LIVE,
+    tool_success: TEXT_DIM,
+    tool_failed: ACCENT_TOOL_ISSUE,
 };
 
 pub const LIGHT_UI_THEME: UiTheme = UiTheme {
@@ -382,19 +620,37 @@ pub const LIGHT_UI_THEME: UiTheme = UiTheme {
     selection_bg: LIGHT_SELECTION_BG,
     header_bg: LIGHT_SURFACE,
     footer_bg: LIGHT_SURFACE,
-    mode_agent: DEEPSEEK_BLUE,
-    mode_yolo: DEEPSEEK_RED,
-    mode_plan: Color::Rgb(180, 83, 9),
-    mode_goal: Color::Rgb(80, 180, 130), // mint green
-    status_ready: LIGHT_TEXT_MUTED,
-    status_working: DEEPSEEK_BLUE,
-    status_warning: Color::Rgb(180, 83, 9),
     text_dim: LIGHT_TEXT_HINT,
     text_hint: LIGHT_TEXT_HINT,
     text_muted: LIGHT_TEXT_MUTED,
     text_body: LIGHT_TEXT_BODY,
     text_soft: LIGHT_TEXT_SOFT,
     border: LIGHT_BORDER,
+    accent_primary: Color::Rgb(53, 120, 229),   // blue
+    accent_secondary: Color::Rgb(79, 180, 160), // teal
+    accent_action: Color::Rgb(220, 90, 60),     // warm coral
+    error_fg: Color::Rgb(200, 40, 60),          // red
+    error_hover: Color::Rgb(220, 70, 85),
+    error_surface: Color::Rgb(254, 229, 229),
+    error_border: Color::Rgb(240, 120, 130),
+    error_text: Color::Rgb(120, 20, 30),
+    warning: Color::Rgb(180, 83, 9),      // amber
+    success: Color::Rgb(21, 128, 61),     // green
+    info: Color::Rgb(53, 120, 229),       // blue
+    mode_agent: Color::Rgb(53, 120, 229), // blue
+    mode_yolo: Color::Rgb(200, 40, 60),   // red
+    mode_plan: Color::Rgb(180, 83, 9),    // amber
+    mode_goal: Color::Rgb(80, 180, 130),  // mint green
+    status_ready: LIGHT_TEXT_MUTED,
+    status_working: Color::Rgb(53, 120, 229),   // blue
+    status_warning: Color::Rgb(180, 83, 9),     // amber
+    diff_added_fg: Color::Rgb(22, 101, 52),     // green
+    diff_deleted_fg: Color::Rgb(200, 40, 60),   // red
+    diff_added_bg: Color::Rgb(223, 247, 231),   // light green
+    diff_deleted_bg: Color::Rgb(254, 229, 229), // light red
+    tool_running: Color::Rgb(53, 120, 229),     // blue
+    tool_success: LIGHT_TEXT_HINT,
+    tool_failed: Color::Rgb(200, 40, 60), // red
 };
 
 pub const GRAYSCALE_UI_THEME: UiTheme = UiTheme {
@@ -407,19 +663,37 @@ pub const GRAYSCALE_UI_THEME: UiTheme = UiTheme {
     selection_bg: GRAYSCALE_SELECTION_BG,
     header_bg: GRAYSCALE_SURFACE,
     footer_bg: GRAYSCALE_SURFACE,
-    mode_agent: GRAYSCALE_TEXT_SOFT,
-    mode_yolo: GRAYSCALE_TEXT_BODY,
-    mode_plan: GRAYSCALE_TEXT_MUTED,
-    mode_goal: GRAYSCALE_TEXT_SOFT,
-    status_ready: GRAYSCALE_TEXT_MUTED,
-    status_working: GRAYSCALE_TEXT_SOFT,
-    status_warning: GRAYSCALE_TEXT_BODY,
     text_dim: GRAYSCALE_TEXT_HINT,
     text_hint: GRAYSCALE_TEXT_HINT,
     text_muted: GRAYSCALE_TEXT_MUTED,
     text_body: GRAYSCALE_TEXT_BODY,
     text_soft: GRAYSCALE_TEXT_SOFT,
     border: GRAYSCALE_BORDER,
+    accent_primary: GRAYSCALE_TEXT_SOFT,
+    accent_secondary: GRAYSCALE_TEXT_MUTED,
+    accent_action: Color::Rgb(210, 210, 210),
+    error_fg: GRAYSCALE_TEXT_BODY,
+    error_hover: GRAYSCALE_TEXT_SOFT,
+    error_surface: GRAYSCALE_ERROR,
+    error_border: GRAYSCALE_BORDER,
+    error_text: GRAYSCALE_TEXT_SOFT,
+    warning: GRAYSCALE_TEXT_MUTED,
+    success: GRAYSCALE_TEXT_SOFT,
+    info: GRAYSCALE_TEXT_MUTED,
+    mode_agent: Color::Rgb(200, 200, 200),
+    mode_yolo: GRAYSCALE_TEXT_BODY,
+    mode_plan: GRAYSCALE_TEXT_MUTED,
+    mode_goal: GRAYSCALE_TEXT_SOFT,
+    status_ready: GRAYSCALE_TEXT_MUTED,
+    status_working: GRAYSCALE_TEXT_SOFT,
+    status_warning: GRAYSCALE_TEXT_BODY,
+    diff_added_fg: GRAYSCALE_TEXT_SOFT,
+    diff_deleted_fg: GRAYSCALE_TEXT_BODY,
+    diff_added_bg: GRAYSCALE_SUCCESS,
+    diff_deleted_bg: GRAYSCALE_ERROR,
+    tool_running: GRAYSCALE_TEXT_SOFT,
+    tool_success: GRAYSCALE_TEXT_HINT,
+    tool_failed: GRAYSCALE_TEXT_BODY,
 };
 
 pub const CATPPUCCIN_MOCHA_UI_THEME: UiTheme = UiTheme {
@@ -432,19 +706,37 @@ pub const CATPPUCCIN_MOCHA_UI_THEME: UiTheme = UiTheme {
     selection_bg: Color::Rgb(0x45, 0x47, 0x5a), // surface1
     header_bg: Color::Rgb(0x11, 0x11, 0x1b),    // crust
     footer_bg: Color::Rgb(0x11, 0x11, 0x1b),
-    mode_agent: Color::Rgb(0x89, 0xb4, 0xfa),     // blue
-    mode_yolo: Color::Rgb(0xf3, 0x8b, 0xa8),      // red
-    mode_plan: Color::Rgb(0xfa, 0xb3, 0x87),      // peach
-    mode_goal: Color::Rgb(0xa6, 0xe3, 0xa1),      // green
-    status_ready: Color::Rgb(0x7f, 0x84, 0x9c),   // overlay1
-    status_working: Color::Rgb(0x74, 0xc7, 0xec), // sapphire
-    status_warning: Color::Rgb(0xf9, 0xe2, 0xaf), // yellow
-    text_dim: Color::Rgb(0x6c, 0x70, 0x86),       // overlay0
-    text_hint: Color::Rgb(0x7f, 0x84, 0x9c),      // overlay1
-    text_muted: Color::Rgb(0xa6, 0xad, 0xc8),     // subtext0
-    text_body: Color::Rgb(0xcd, 0xd6, 0xf4),      // text
-    text_soft: Color::Rgb(0xba, 0xc2, 0xde),      // subtext1
-    border: Color::Rgb(0x45, 0x47, 0x5a),         // surface1
+    text_dim: Color::Rgb(0x6c, 0x70, 0x86),         // overlay0
+    text_hint: Color::Rgb(0x7f, 0x84, 0x9c),        // overlay1
+    text_muted: Color::Rgb(0xa6, 0xad, 0xc8),       // subtext0
+    text_body: Color::Rgb(0xcd, 0xd6, 0xf4),        // text
+    text_soft: Color::Rgb(0xba, 0xc2, 0xde),        // subtext1
+    border: Color::Rgb(0x45, 0x47, 0x5a),           // surface1
+    accent_primary: Color::Rgb(0x89, 0xb4, 0xfa),   // blue
+    accent_secondary: Color::Rgb(0x74, 0xc7, 0xec), // sapphire
+    accent_action: Color::Rgb(0xfa, 0xb3, 0x87),    // peach
+    error_fg: Color::Rgb(0xf3, 0x8b, 0xa8),         // red
+    error_hover: Color::Rgb(0xf5, 0xa2, 0xbc),
+    error_surface: Color::Rgb(0x3a, 0x1f, 0x2a),
+    error_border: Color::Rgb(0xf3, 0x8b, 0xa8),
+    error_text: Color::Rgb(0xf5, 0xc2, 0xd0),
+    warning: Color::Rgb(0xf9, 0xe2, 0xaf),         // yellow
+    success: Color::Rgb(0xa6, 0xe3, 0xa1),         // green
+    info: Color::Rgb(0x89, 0xd9, 0xeb),            // sky
+    mode_agent: Color::Rgb(0x89, 0xb4, 0xfa),      // blue
+    mode_yolo: Color::Rgb(0xf3, 0x8b, 0xa8),       // red
+    mode_plan: Color::Rgb(0xfa, 0xb3, 0x87),       // peach
+    mode_goal: Color::Rgb(0xa6, 0xe3, 0xa1),       // green
+    status_ready: Color::Rgb(0x7f, 0x84, 0x9c),    // overlay1
+    status_working: Color::Rgb(0x74, 0xc7, 0xec),  // sapphire
+    status_warning: Color::Rgb(0xf9, 0xe2, 0xaf),  // yellow
+    diff_added_fg: Color::Rgb(0xa6, 0xe3, 0xa1),   // green
+    diff_deleted_fg: Color::Rgb(0xf3, 0x8b, 0xa8), // red
+    diff_added_bg: Color::Rgb(0x1f, 0x33, 0x29),
+    diff_deleted_bg: Color::Rgb(0x3a, 0x1f, 0x2a),
+    tool_running: Color::Rgb(0x74, 0xc7, 0xec), // sapphire
+    tool_success: Color::Rgb(0x7f, 0x84, 0x9c), // overlay1
+    tool_failed: Color::Rgb(0xf3, 0x8b, 0xa8),  // red
 };
 
 pub const TOKYO_NIGHT_UI_THEME: UiTheme = UiTheme {
@@ -457,19 +749,37 @@ pub const TOKYO_NIGHT_UI_THEME: UiTheme = UiTheme {
     selection_bg: Color::Rgb(0x28, 0x34, 0x57), // visual selection
     header_bg: Color::Rgb(0x16, 0x16, 0x1e),
     footer_bg: Color::Rgb(0x16, 0x16, 0x1e),
-    mode_agent: Color::Rgb(0x7a, 0xa2, 0xf7),     // blue
-    mode_yolo: Color::Rgb(0xf7, 0x76, 0x8e),      // red
-    mode_plan: Color::Rgb(0xff, 0x9e, 0x64),      // orange
-    mode_goal: Color::Rgb(0x9e, 0xce, 0x6a),      // green
-    status_ready: Color::Rgb(0x56, 0x5f, 0x89),   // comment
-    status_working: Color::Rgb(0x7d, 0xcf, 0xff), // cyan
-    status_warning: Color::Rgb(0xe0, 0xaf, 0x68), // yellow
-    text_dim: Color::Rgb(0x56, 0x5f, 0x89),       // comment
-    text_hint: Color::Rgb(0x73, 0x7a, 0xa2),      // dark5
-    text_muted: Color::Rgb(0xa9, 0xb1, 0xd6),     // fg_dark
-    text_body: Color::Rgb(0xc0, 0xca, 0xf5),      // fg
+    text_dim: Color::Rgb(0x56, 0x5f, 0x89),   // comment
+    text_hint: Color::Rgb(0x73, 0x7a, 0xa2),  // dark5
+    text_muted: Color::Rgb(0xa9, 0xb1, 0xd6), // fg_dark
+    text_body: Color::Rgb(0xc0, 0xca, 0xf5),  // fg
     text_soft: Color::Rgb(0xbb, 0xc2, 0xe0),
     border: Color::Rgb(0x41, 0x48, 0x68), // terminal_black
+    accent_primary: Color::Rgb(0x7a, 0xa2, 0xf7), // blue
+    accent_secondary: Color::Rgb(0x7d, 0xcf, 0xff), // cyan
+    accent_action: Color::Rgb(0xff, 0x9e, 0x64), // orange
+    error_fg: Color::Rgb(0xf7, 0x76, 0x8e), // red
+    error_hover: Color::Rgb(0xf9, 0x92, 0xa4),
+    error_surface: Color::Rgb(0x33, 0x1c, 0x24),
+    error_border: Color::Rgb(0xf7, 0x76, 0x8e),
+    error_text: Color::Rgb(0xfa, 0xcc, 0xd4),
+    warning: Color::Rgb(0xe0, 0xaf, 0x68),         // yellow
+    success: Color::Rgb(0x9e, 0xce, 0x6a),         // green
+    info: Color::Rgb(0x7d, 0xcf, 0xff),            // cyan
+    mode_agent: Color::Rgb(0x7a, 0xa2, 0xf7),      // blue
+    mode_yolo: Color::Rgb(0xf7, 0x76, 0x8e),       // red
+    mode_plan: Color::Rgb(0xff, 0x9e, 0x64),       // orange
+    mode_goal: Color::Rgb(0x9e, 0xce, 0x6a),       // green
+    status_ready: Color::Rgb(0x56, 0x5f, 0x89),    // comment
+    status_working: Color::Rgb(0x7d, 0xcf, 0xff),  // cyan
+    status_warning: Color::Rgb(0xe0, 0xaf, 0x68),  // yellow
+    diff_added_fg: Color::Rgb(0x9e, 0xce, 0x6a),   // green
+    diff_deleted_fg: Color::Rgb(0xf7, 0x76, 0x8e), // red
+    diff_added_bg: Color::Rgb(0x1b, 0x2b, 0x1f),
+    diff_deleted_bg: Color::Rgb(0x33, 0x1c, 0x24),
+    tool_running: Color::Rgb(0x7d, 0xcf, 0xff), // cyan
+    tool_success: Color::Rgb(0x56, 0x5f, 0x89), // comment
+    tool_failed: Color::Rgb(0xf7, 0x76, 0x8e),  // red
 };
 
 pub const DRACULA_UI_THEME: UiTheme = UiTheme {
@@ -482,19 +792,94 @@ pub const DRACULA_UI_THEME: UiTheme = UiTheme {
     selection_bg: Color::Rgb(0x44, 0x47, 0x5a), // current line
     header_bg: Color::Rgb(0x21, 0x22, 0x2c),
     footer_bg: Color::Rgb(0x21, 0x22, 0x2c),
-    mode_agent: Color::Rgb(0xbd, 0x93, 0xf9),     // purple
-    mode_yolo: Color::Rgb(0xff, 0x55, 0x55),      // red
-    mode_plan: Color::Rgb(0xff, 0xb8, 0x6c),      // orange
-    mode_goal: Color::Rgb(0x50, 0xfa, 0x7b),      // green
-    status_ready: Color::Rgb(0x62, 0x72, 0xa4),   // comment
-    status_working: Color::Rgb(0x8b, 0xe9, 0xfd), // cyan
-    status_warning: Color::Rgb(0xf1, 0xfa, 0x8c), // yellow
-    text_dim: Color::Rgb(0x62, 0x72, 0xa4),
+    text_dim: Color::Rgb(0x62, 0x72, 0xa4), // comment
     text_hint: Color::Rgb(0x8a, 0x8e, 0xaa),
     text_muted: Color::Rgb(0xc0, 0xc4, 0xd6),
     text_body: Color::Rgb(0xf8, 0xf8, 0xf2), // foreground
     text_soft: Color::Rgb(0xe2, 0xe2, 0xdc),
     border: Color::Rgb(0x44, 0x47, 0x5a),
+    accent_primary: Color::Rgb(0xbd, 0x93, 0xf9), // purple
+    accent_secondary: Color::Rgb(0x8b, 0xe9, 0xfd), // cyan
+    accent_action: Color::Rgb(0xff, 0xb8, 0x6c),  // orange
+    error_fg: Color::Rgb(0xff, 0x55, 0x55),       // red
+    error_hover: Color::Rgb(0xff, 0x7c, 0x7c),
+    error_surface: Color::Rgb(0x3a, 0x1f, 0x22),
+    error_border: Color::Rgb(0xff, 0x55, 0x55),
+    error_text: Color::Rgb(0xff, 0xbb, 0xbb),
+    warning: Color::Rgb(0xf1, 0xfa, 0x8c),         // yellow
+    success: Color::Rgb(0x50, 0xfa, 0x7b),         // green
+    info: Color::Rgb(0x8b, 0xe9, 0xfd),            // cyan
+    mode_agent: Color::Rgb(0xbd, 0x93, 0xf9),      // purple
+    mode_yolo: Color::Rgb(0xff, 0x55, 0x55),       // red
+    mode_plan: Color::Rgb(0xff, 0xb8, 0x6c),       // orange
+    mode_goal: Color::Rgb(0x50, 0xfa, 0x7b),       // green
+    status_ready: Color::Rgb(0x62, 0x72, 0xa4),    // comment
+    status_working: Color::Rgb(0x8b, 0xe9, 0xfd),  // cyan
+    status_warning: Color::Rgb(0xf1, 0xfa, 0x8c),  // yellow
+    diff_added_fg: Color::Rgb(0x50, 0xfa, 0x7b),   // green
+    diff_deleted_fg: Color::Rgb(0xff, 0x55, 0x55), // red
+    diff_added_bg: Color::Rgb(0x21, 0x3a, 0x2a),
+    diff_deleted_bg: Color::Rgb(0x3a, 0x1f, 0x22),
+    tool_running: Color::Rgb(0x8b, 0xe9, 0xfd), // cyan
+    tool_success: Color::Rgb(0x62, 0x72, 0xa4), // comment
+    tool_failed: Color::Rgb(0xff, 0x55, 0x55),  // red
+};
+
+/// "Terminal" theme: lets the host terminal's color scheme show through
+/// instead of painting any RGB surface. Backgrounds use `Color::Reset`
+/// (the terminal's own default bg) and most text uses `Color::Reset`
+/// (terminal's own default fg). Accents are ANSI named colors so they
+/// also inherit the user's terminal palette (Solarized, Nord, custom
+/// schemes, etc.) rather than DeepSeek brand RGB.
+pub const TERMINAL_UI_THEME: UiTheme = UiTheme {
+    name: "terminal",
+    // Mode is reported as Dark to avoid the dark→light cell remap kicking
+    // in; the terminal-theme cell remap already normalizes everything to
+    // `Color::Reset`, and we never want a second pass overwriting that.
+    mode: PaletteMode::Dark,
+    surface_bg: Color::Reset,
+    panel_bg: Color::Reset,
+    elevated_bg: Color::Reset,
+    composer_bg: Color::Reset,
+    selection_bg: Color::Reset,
+    header_bg: Color::Reset,
+    footer_bg: Color::Reset,
+    text_dim: Color::Reset,
+    text_hint: Color::Reset,
+    text_muted: Color::Reset,
+    text_body: Color::Reset,
+    text_soft: Color::Reset,
+    border: Color::Reset,
+    accent_primary: Color::Blue,
+    accent_secondary: Color::Cyan,
+    accent_action: Color::Yellow,
+    error_fg: Color::Red,
+    error_hover: Color::Red,
+    error_surface: Color::Reset,
+    error_border: Color::Red,
+    error_text: Color::Red,
+    warning: Color::Yellow,
+    success: Color::Green,
+    info: Color::Cyan,
+    mode_agent: Color::Blue,
+    mode_yolo: Color::Red,
+    // Magenta keeps Plan visually distinct from `status_warning` (yellow)
+    // so the mode indicator and warning chip don't collide on themes that
+    // render both in the status row.
+    mode_plan: Color::Magenta,
+    mode_goal: Color::Green,
+    // DarkGray gives "Ready" a low-contrast but still distinguishable hue
+    // versus default body text (which is `Color::Reset` on this theme).
+    status_ready: Color::DarkGray,
+    status_working: Color::Cyan,
+    status_warning: Color::Yellow,
+    diff_added_fg: Color::Green,
+    diff_deleted_fg: Color::Red,
+    diff_added_bg: Color::Reset,
+    diff_deleted_bg: Color::Reset,
+    tool_running: Color::Cyan,
+    tool_success: Color::Green,
+    tool_failed: Color::Red,
 };
 
 pub const GRUVBOX_DARK_UI_THEME: UiTheme = UiTheme {
@@ -507,19 +892,37 @@ pub const GRUVBOX_DARK_UI_THEME: UiTheme = UiTheme {
     selection_bg: Color::Rgb(0x66, 0x5c, 0x54), // bg3
     header_bg: Color::Rgb(0x1d, 0x20, 0x21),    // bg0_h
     footer_bg: Color::Rgb(0x1d, 0x20, 0x21),
-    mode_agent: Color::Rgb(0x83, 0xa5, 0x98),     // blue
-    mode_yolo: Color::Rgb(0xfb, 0x49, 0x34),      // red
-    mode_plan: Color::Rgb(0xfe, 0x80, 0x19),      // orange
-    mode_goal: Color::Rgb(0x8e, 0xc0, 0x7c),      // green
-    status_ready: Color::Rgb(0x92, 0x83, 0x74),   // gray
-    status_working: Color::Rgb(0x8e, 0xc0, 0x7c), // aqua
-    status_warning: Color::Rgb(0xfa, 0xbd, 0x2f), // yellow
-    text_dim: Color::Rgb(0x92, 0x83, 0x74),       // gray
-    text_hint: Color::Rgb(0xa8, 0x99, 0x84),      // fg4
-    text_muted: Color::Rgb(0xbd, 0xae, 0x93),     // fg3
-    text_body: Color::Rgb(0xeb, 0xdb, 0xb2),      // fg1
-    text_soft: Color::Rgb(0xd5, 0xc4, 0xa1),      // fg2
-    border: Color::Rgb(0x66, 0x5c, 0x54),         // bg3
+    text_dim: Color::Rgb(0x92, 0x83, 0x74),         // gray
+    text_hint: Color::Rgb(0xa8, 0x99, 0x84),        // fg4
+    text_muted: Color::Rgb(0xbd, 0xae, 0x93),       // fg3
+    text_body: Color::Rgb(0xeb, 0xdb, 0xb2),        // fg1
+    text_soft: Color::Rgb(0xd5, 0xc4, 0xa1),        // fg2
+    border: Color::Rgb(0x66, 0x5c, 0x54),           // bg3
+    accent_primary: Color::Rgb(0x83, 0xa5, 0x98),   // blue
+    accent_secondary: Color::Rgb(0x8e, 0xc0, 0x7c), // aqua/green
+    accent_action: Color::Rgb(0xfe, 0x80, 0x19),    // orange
+    error_fg: Color::Rgb(0xfb, 0x49, 0x34),         // red
+    error_hover: Color::Rgb(0xfc, 0x7c, 0x6b),
+    error_surface: Color::Rgb(0x35, 0x1c, 0x18),
+    error_border: Color::Rgb(0xfb, 0x49, 0x34),
+    error_text: Color::Rgb(0xfc, 0xc4, 0xb8),
+    warning: Color::Rgb(0xfa, 0xbd, 0x2f),         // yellow
+    success: Color::Rgb(0x8e, 0xc0, 0x7c),         // green
+    info: Color::Rgb(0x83, 0xa5, 0x98),            // blue
+    mode_agent: Color::Rgb(0x83, 0xa5, 0x98),      // blue
+    mode_yolo: Color::Rgb(0xfb, 0x49, 0x34),       // red
+    mode_plan: Color::Rgb(0xfe, 0x80, 0x19),       // orange
+    mode_goal: Color::Rgb(0x8e, 0xc0, 0x7c),       // green
+    status_ready: Color::Rgb(0x92, 0x83, 0x74),    // gray
+    status_working: Color::Rgb(0x8e, 0xc0, 0x7c),  // aqua
+    status_warning: Color::Rgb(0xfa, 0xbd, 0x2f),  // yellow
+    diff_added_fg: Color::Rgb(0x8e, 0xc0, 0x7c),   // green
+    diff_deleted_fg: Color::Rgb(0xfb, 0x49, 0x34), // red
+    diff_added_bg: Color::Rgb(0x29, 0x32, 0x16),
+    diff_deleted_bg: Color::Rgb(0x35, 0x1c, 0x18),
+    tool_running: Color::Rgb(0x8e, 0xc0, 0x7c), // aqua
+    tool_success: Color::Rgb(0x92, 0x83, 0x74), // gray
+    tool_failed: Color::Rgb(0xfb, 0x49, 0x34),  // red
 };
 
 /// Stable identifiers for the named themes the user can select. `System`
@@ -528,6 +931,7 @@ pub const GRUVBOX_DARK_UI_THEME: UiTheme = UiTheme {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ThemeId {
     System,
+    Terminal,
     Whale,
     WhaleLight,
     Grayscale,
@@ -545,6 +949,7 @@ impl ThemeId {
     pub fn from_name(value: &str) -> Option<Self> {
         match normalize_theme_name(value)? {
             "system" => Some(Self::System),
+            "terminal" => Some(Self::Terminal),
             "dark" => Some(Self::Whale),
             "light" => Some(Self::WhaleLight),
             "grayscale" => Some(Self::Grayscale),
@@ -562,6 +967,7 @@ impl ThemeId {
     pub const fn name(self) -> &'static str {
         match self {
             Self::System => "system",
+            Self::Terminal => "terminal",
             Self::Whale => "dark",
             Self::WhaleLight => "light",
             Self::Grayscale => "grayscale",
@@ -577,6 +983,7 @@ impl ThemeId {
     pub const fn display_name(self) -> &'static str {
         match self {
             Self::System => "System",
+            Self::Terminal => "Terminal",
             Self::Whale => "Whale (Dark)",
             Self::WhaleLight => "Whale Light",
             Self::Grayscale => "Grayscale",
@@ -592,7 +999,8 @@ impl ThemeId {
     pub const fn tagline(self) -> &'static str {
         match self {
             Self::System => "Follow terminal background (COLORFGBG / macOS appearance)",
-            Self::Whale => "Default DeepSeek dark blue",
+            Self::Terminal => "Inherit terminal colors fully (transparent surfaces, ANSI accents)",
+            Self::Whale => "Whale dark — deep navy & gold",
             Self::WhaleLight => "DeepSeek light, paper-ish",
             Self::Grayscale => "Color-minimal high contrast",
             Self::CatppuccinMocha => "Soft pastels on warm dark",
@@ -610,6 +1018,7 @@ impl ThemeId {
     pub fn ui_theme(self) -> UiTheme {
         match self {
             Self::System => UiTheme::detect(),
+            Self::Terminal => TERMINAL_UI_THEME,
             Self::Whale => UI_THEME,
             Self::WhaleLight => LIGHT_UI_THEME,
             Self::Grayscale => GRAYSCALE_UI_THEME,
@@ -624,6 +1033,7 @@ impl ThemeId {
 /// Themes shown in the `/theme` picker, in display order.
 pub const SELECTABLE_THEMES: &[ThemeId] = &[
     ThemeId::System,
+    ThemeId::Terminal,
     ThemeId::Whale,
     ThemeId::WhaleLight,
     ThemeId::Grayscale,
@@ -666,6 +1076,7 @@ impl UiTheme {
 pub fn normalize_theme_name(value: &str) -> Option<&'static str> {
     match value.trim().to_ascii_lowercase().as_str() {
         "" | "auto" | "system" | "default" => Some("system"),
+        "terminal" | "term" | "transparent" | "follow-terminal" | "inherit" => Some("terminal"),
         "dark" | "whale" | "whale-dark" => Some("dark"),
         "light" | "whale-light" => Some("light"),
         "grayscale" | "greyscale" | "gray" | "grey" | "mono" | "monochrome" | "black-white"
@@ -809,54 +1220,30 @@ fn adapt_bg_for_light_palette(color: Color) -> Color {
 // no-op — the existing dark/light pipeline handles those.
 
 /// Per-preset green accent used for things that semantically *should* stay
-/// green even after theming (diff "+" lines, user-input body). Mapping these
-/// to `ui.status_working` would lose the green/cyan distinction the UI
-/// relies on, so we keep a small dedicated table.
+/// green even after theming (diff "+" lines, user-input body). Now delegates
+/// to the active UiTheme's diff_added_fg.
 #[must_use]
-const fn theme_green(theme: ThemeId) -> Color {
-    match theme {
-        ThemeId::CatppuccinMocha => Color::Rgb(0xa6, 0xe3, 0xa1),
-        ThemeId::TokyoNight => Color::Rgb(0x9e, 0xce, 0x6a),
-        ThemeId::Dracula => Color::Rgb(0x50, 0xfa, 0x7b),
-        ThemeId::GruvboxDark => Color::Rgb(0xb8, 0xbb, 0x26),
-        _ => USER_BODY,
-    }
+const fn theme_green(ui: &UiTheme) -> Color {
+    ui.diff_added_fg
 }
 
 /// Per-preset red accent, used for diff "−" line foreground when present.
 #[must_use]
-const fn theme_red(theme: ThemeId) -> Color {
-    match theme {
-        ThemeId::CatppuccinMocha => Color::Rgb(0xf3, 0x8b, 0xa8),
-        ThemeId::TokyoNight => Color::Rgb(0xf7, 0x76, 0x8e),
-        ThemeId::Dracula => Color::Rgb(0xff, 0x55, 0x55),
-        ThemeId::GruvboxDark => Color::Rgb(0xfb, 0x49, 0x34),
-        _ => DEEPSEEK_RED,
-    }
+#[allow(dead_code)]
+const fn theme_red(ui: &UiTheme) -> Color {
+    ui.diff_deleted_fg
 }
 
 /// Per-preset dark-green diff-added background tint.
 #[must_use]
-const fn theme_diff_added_bg(theme: ThemeId) -> Color {
-    match theme {
-        ThemeId::CatppuccinMocha => Color::Rgb(0x1f, 0x33, 0x29),
-        ThemeId::TokyoNight => Color::Rgb(0x1b, 0x2b, 0x1f),
-        ThemeId::Dracula => Color::Rgb(0x21, 0x3a, 0x2a),
-        ThemeId::GruvboxDark => Color::Rgb(0x29, 0x32, 0x16),
-        _ => DIFF_ADDED_BG,
-    }
+const fn theme_diff_added_bg(ui: &UiTheme) -> Color {
+    ui.diff_added_bg
 }
 
 /// Per-preset dark-red diff-deleted background tint.
 #[must_use]
-const fn theme_diff_deleted_bg(theme: ThemeId) -> Color {
-    match theme {
-        ThemeId::CatppuccinMocha => Color::Rgb(0x3a, 0x1f, 0x2a),
-        ThemeId::TokyoNight => Color::Rgb(0x33, 0x1c, 0x24),
-        ThemeId::Dracula => Color::Rgb(0x3a, 0x1f, 0x22),
-        ThemeId::GruvboxDark => Color::Rgb(0x35, 0x1c, 0x18),
-        _ => DIFF_DELETED_BG,
-    }
+const fn theme_diff_deleted_bg(ui: &UiTheme) -> Color {
+    ui.diff_deleted_bg
 }
 
 /// Returns `true` if the preset participates in the cell-level remap. The
@@ -867,7 +1254,11 @@ const fn theme_diff_deleted_bg(theme: ThemeId) -> Color {
 pub const fn theme_remap_active(theme: ThemeId) -> bool {
     matches!(
         theme,
-        ThemeId::CatppuccinMocha | ThemeId::TokyoNight | ThemeId::Dracula | ThemeId::GruvboxDark
+        ThemeId::Terminal
+            | ThemeId::CatppuccinMocha
+            | ThemeId::TokyoNight
+            | ThemeId::Dracula
+            | ThemeId::GruvboxDark
     )
 }
 
@@ -905,13 +1296,12 @@ pub fn adapt_fg_for_theme(color: Color, theme: ThemeId, ui: &UiTheme) -> Color {
     } else if color == ACCENT_TOOL_ISSUE {
         ui.mode_yolo
     } else if color == STATUS_WARNING {
-        ui.status_warning
-    } else if color == DEEPSEEK_RED {
-        theme_red(theme)
+        ui.warning
+    } else if color == STATUS_ERROR || color == DEEPSEEK_RED {
+        ui.error_fg
     } else if color == DIFF_ADDED || color == USER_BODY {
-        theme_green(theme)
+        theme_green(ui)
     } else if color == DEEPSEEK_BLUE {
-        // The default mode_agent accent — keep it in the preset's blue family.
         ui.mode_agent
     } else {
         color
@@ -939,19 +1329,18 @@ pub fn adapt_bg_for_theme(color: Color, theme: ThemeId, ui: &UiTheme) -> Color {
     } else if color == SURFACE_REASONING
         || color == SURFACE_REASONING_TINT
         || color == SURFACE_REASONING_ACTIVE
-        || color == SURFACE_SUCCESS
-        || color == SURFACE_ERROR
     {
-        // Reasoning/success/error backgrounds are subtle tints that don't have
-        // a dedicated theme slot. Collapse them onto the panel surface so they
-        // read as recessed rather than a stray default-blue tint.
         ui.panel_bg
+    } else if color == SURFACE_SUCCESS {
+        ui.diff_added_bg
+    } else if color == SURFACE_ERROR {
+        ui.error_surface
     } else if color == SELECTION_BG {
         ui.selection_bg
     } else if color == DIFF_ADDED_BG {
-        theme_diff_added_bg(theme)
+        theme_diff_added_bg(ui)
     } else if color == DIFF_DELETED_BG {
-        theme_diff_deleted_bg(theme)
+        theme_diff_deleted_bg(ui)
     } else {
         color
     }
@@ -1098,8 +1487,7 @@ fn grayscale_bg_from_luma(luma: u8) -> Color {
 }
 
 fn luma(r: u8, g: u8, b: u8) -> u8 {
-    let weighted = u32::from(r) * 299 + u32::from(g) * 587 + u32::from(b) * 114;
-    (weighted / 1000) as u8
+    ((u32::from(r) * 299 + u32::from(g) * 587 + u32::from(b) * 114 + 500) / 1000) as u8
 }
 // === Color depth + brightness helpers (v0.6.6 UI redesign) ===
 
@@ -1209,10 +1597,9 @@ pub fn blend(fg: Color, bg: Color, alpha: f32) -> Color {
     }
 }
 
-/// Return the reasoning surface color tinted at 12% over the app background.
-/// This is the headline reasoning treatment in v0.6.6; a 12% blend keeps the
-/// warm bias subtle without competing with body text. Returns `None` when the
-/// terminal can't render the bg faithfully.
+/// Return the dedicated reasoning surface tint for terminals that can render
+/// background colors faithfully. ANSI-16 terminals disable the tint because
+/// the nearest named background is too coarse for this subtle treatment.
 #[must_use]
 pub fn reasoning_surface_tint(depth: ColorDepth) -> Option<Color> {
     match depth {
@@ -1359,13 +1746,15 @@ fn rgb_to_ansi256(r: u8, g: u8, b: u8) -> u8 {
 mod tests {
     use super::{
         ACCENT_REASONING_LIVE, ColorDepth, DEEPSEEK_INK, DEEPSEEK_RED, DEEPSEEK_SKY,
-        DEEPSEEK_SLATE, GRAYSCALE_BORDER, GRAYSCALE_ELEVATED, GRAYSCALE_PANEL, GRAYSCALE_REASONING,
-        GRAYSCALE_SURFACE, GRAYSCALE_TEXT_BODY, GRAYSCALE_TEXT_HINT, GRAYSCALE_TEXT_SOFT,
-        GRAYSCALE_UI_THEME, LIGHT_BORDER, LIGHT_ELEVATED, LIGHT_PANEL, LIGHT_REASONING,
-        LIGHT_SURFACE, LIGHT_TEXT_BODY, LIGHT_TEXT_HINT, LIGHT_UI_THEME, PaletteMode,
-        SURFACE_REASONING, SURFACE_REASONING_TINT, TEXT_BODY, TEXT_HINT, TEXT_REASONING,
-        TEXT_TOOL_OUTPUT, UI_THEME, adapt_bg, adapt_bg_for_palette_mode, adapt_color,
-        adapt_fg_for_palette_mode, blend, luma, nearest_ansi16, normalize_hex_rgb_color,
+        DEEPSEEK_SLATE, DIFF_ADDED, DIFF_ADDED_BG, GRAYSCALE_BORDER, GRAYSCALE_ELEVATED,
+        GRAYSCALE_PANEL, GRAYSCALE_REASONING, GRAYSCALE_SURFACE, GRAYSCALE_TEXT_BODY,
+        GRAYSCALE_TEXT_HINT, GRAYSCALE_TEXT_SOFT, GRAYSCALE_UI_THEME, LIGHT_BORDER, LIGHT_ELEVATED,
+        LIGHT_PANEL, LIGHT_REASONING, LIGHT_SURFACE, LIGHT_TEXT_BODY, LIGHT_TEXT_HINT,
+        LIGHT_UI_THEME, PaletteMode, SURFACE_REASONING, SURFACE_REASONING_TINT, TERMINAL_UI_THEME,
+        TEXT_BODY, TEXT_HINT, TEXT_REASONING, TEXT_TOOL_OUTPUT, ThemeId, UI_THEME,
+        WHALE_REASONING_TEXT_RGB, WHALE_REASONING_TINT_RGB, WHALE_TEXT_BODY_RGB, adapt_bg,
+        adapt_bg_for_palette_mode, adapt_bg_for_theme, adapt_color, adapt_fg_for_palette_mode,
+        adapt_fg_for_theme, blend, luma, nearest_ansi16, normalize_hex_rgb_color,
         normalize_theme_name, parse_hex_rgb_color, pulse_brightness, reasoning_surface_tint,
         rgb_to_ansi256, theme_label_for_mode, ui_theme_from_settings,
     };
@@ -1451,12 +1840,39 @@ mod tests {
         assert_eq!(normalize_theme_name("system"), Some("system"));
         assert_eq!(normalize_theme_name("default"), Some("system"));
         assert_eq!(normalize_theme_name("whale"), Some("dark"));
+        assert_eq!(normalize_theme_name("transparent"), Some("terminal"));
+        assert_eq!(normalize_theme_name("inherit"), Some("terminal"));
         assert_eq!(normalize_theme_name("black-white"), Some("grayscale"));
         assert_eq!(normalize_theme_name("mono"), Some("grayscale"));
         assert_eq!(normalize_theme_name("solarized"), None);
         assert_eq!(theme_label_for_mode(PaletteMode::Grayscale), "grayscale");
     }
 
+    #[test]
+    fn terminal_theme_resets_surfaces_and_remaps_direct_palette_constants() {
+        assert_eq!(ThemeId::from_name("terminal"), Some(ThemeId::Terminal));
+        assert_eq!(TERMINAL_UI_THEME.surface_bg, Color::Reset);
+        assert_eq!(TERMINAL_UI_THEME.footer_bg, Color::Reset);
+        assert_eq!(TERMINAL_UI_THEME.text_body, Color::Reset);
+
+        assert_eq!(
+            adapt_bg_for_theme(DEEPSEEK_INK, ThemeId::Terminal, &TERMINAL_UI_THEME),
+            Color::Reset
+        );
+        assert_eq!(
+            adapt_bg_for_theme(DIFF_ADDED_BG, ThemeId::Terminal, &TERMINAL_UI_THEME),
+            Color::Reset
+        );
+        assert_eq!(
+            adapt_fg_for_theme(TEXT_BODY, ThemeId::Terminal, &TERMINAL_UI_THEME),
+            Color::Reset
+        );
+        assert_eq!(
+            adapt_fg_for_theme(DIFF_ADDED, ThemeId::Terminal, &TERMINAL_UI_THEME),
+            Color::Green
+        );
+    }
+
     #[test]
     fn light_palette_has_quiet_layer_separation() {
         assert_eq!(LIGHT_SURFACE, Color::Rgb(246, 248, 251));
@@ -1469,9 +1885,30 @@ mod tests {
 
     #[test]
     fn dark_palette_uses_soft_body_text_and_warm_reasoning() {
-        assert_eq!(TEXT_BODY, Color::Rgb(226, 232, 240));
-        assert_eq!(TEXT_REASONING, Color::Rgb(211, 170, 112));
-        assert_eq!(ACCENT_REASONING_LIVE, Color::Rgb(224, 153, 72));
+        assert_eq!(
+            TEXT_BODY,
+            Color::Rgb(
+                WHALE_TEXT_BODY_RGB.0,
+                WHALE_TEXT_BODY_RGB.1,
+                WHALE_TEXT_BODY_RGB.2
+            )
+        );
+        assert_eq!(
+            TEXT_REASONING,
+            Color::Rgb(
+                WHALE_REASONING_TEXT_RGB.0,
+                WHALE_REASONING_TEXT_RGB.1,
+                WHALE_REASONING_TEXT_RGB.2
+            )
+        );
+        assert_eq!(
+            ACCENT_REASONING_LIVE,
+            Color::Rgb(
+                WHALE_REASONING_TEXT_RGB.0,
+                WHALE_REASONING_TEXT_RGB.1,
+                WHALE_REASONING_TEXT_RGB.2
+            )
+        );
         assert_ne!(TEXT_REASONING, TEXT_TOOL_OUTPUT);
         assert_ne!(TEXT_BODY, Color::White);
     }
@@ -1605,8 +2042,12 @@ mod tests {
             adapt_color(DEEPSEEK_SKY, ColorDepth::Ansi16),
             Color::LightBlue
         );
-        // Red: red-dominant, mid lum → Red (not the bright variant).
-        assert_eq!(adapt_color(DEEPSEEK_RED, ColorDepth::Ansi16), Color::Red);
+        // Rose Red is intentionally bright enough to use the terminal's
+        // bright red slot.
+        assert_eq!(
+            adapt_color(DEEPSEEK_RED, ColorDepth::Ansi16),
+            Color::LightRed
+        );
     }
 
     #[test]
@@ -1634,8 +2075,12 @@ mod tests {
     #[test]
     fn light_palette_maps_reasoning_tint_to_light_surface() {
         assert_eq!(
-            blend(SURFACE_REASONING, DEEPSEEK_INK, 0.12),
-            SURFACE_REASONING_TINT
+            SURFACE_REASONING_TINT,
+            Color::Rgb(
+                WHALE_REASONING_TINT_RGB.0,
+                WHALE_REASONING_TINT_RGB.1,
+                WHALE_REASONING_TINT_RGB.2
+            )
         );
         assert_eq!(
             adapt_bg_for_palette_mode(SURFACE_REASONING_TINT, PaletteMode::Light),
@@ -1694,14 +2139,13 @@ mod tests {
 
     #[test]
     fn nearest_ansi16_routes_known_brand_colors() {
-        // Blue-dominant brand colors should stay blue rather than collapsing
-        // to the user's terminal cyan, which is often much louder.
-        assert_eq!(nearest_ansi16(53, 120, 229), Color::Blue);
-        assert_eq!(nearest_ansi16(106, 174, 242), Color::LightBlue);
-        assert_eq!(nearest_ansi16(42, 74, 127), Color::Blue);
-        assert_eq!(nearest_ansi16(54, 187, 212), Color::LightCyan);
-        assert_eq!(nearest_ansi16(226, 80, 96), Color::Red);
-        assert_eq!(nearest_ansi16(11, 21, 38), Color::Black);
+        // v0.8.45: accent primary is Signal Gold (#F6C453), secondary is Seafoam.
+        assert_eq!(nearest_ansi16(246, 196, 83), Color::LightYellow); // Signal Gold
+        assert_eq!(nearest_ansi16(79, 209, 197), Color::LightCyan); // Seafoam
+        assert_eq!(nearest_ansi16(42, 74, 127), Color::Blue); // Border
+        assert_eq!(nearest_ansi16(54, 187, 212), Color::LightCyan); // Aqua
+        assert_eq!(nearest_ansi16(255, 92, 122), Color::LightRed); // Rose Red
+        assert_eq!(nearest_ansi16(13, 21, 37), Color::Black); // Deep Navy
     }
 
     #[test]
diff --git a/crates/tui/src/pricing.rs b/crates/tui/src/pricing.rs
index 750f9830..eb78ed8b 100644
--- a/crates/tui/src/pricing.rs
+++ b/crates/tui/src/pricing.rs
@@ -201,6 +201,25 @@ fn calculate_turn_cost_from_usage_with_pricing(pricing: CurrencyPricing, usage:
     hit_cost + miss_cost + output_cost
 }
 
+/// Estimate how much money was saved by serving `cache_hit_tokens` from the
+/// prefix cache instead of billing them at the cache-miss rate.  Returns `None`
+/// when the model's pricing is unknown or the number of cache-hit tokens is
+/// zero (nothing to save).
+#[must_use]
+pub fn calculate_cache_savings(model: &str, cache_hit_tokens: u32) -> Option<CostEstimate> {
+    if cache_hit_tokens == 0 {
+        return None;
+    }
+    let pricing = pricing_for_model(model)?;
+    let tokens = cache_hit_tokens as f64 / 1_000_000.0;
+    Some(CostEstimate {
+        usd: tokens
+            * (pricing.usd.input_cache_miss_per_million - pricing.usd.input_cache_hit_per_million),
+        cny: tokens
+            * (pricing.cny.input_cache_miss_per_million - pricing.cny.input_cache_hit_per_million),
+    })
+}
+
 /// Format a USD cost for compact display.
 #[must_use]
 #[allow(dead_code)]
diff --git a/crates/tui/src/project_context.rs b/crates/tui/src/project_context.rs
index 7ff922d4..d6c3a4c5 100644
--- a/crates/tui/src/project_context.rs
+++ b/crates/tui/src/project_context.rs
@@ -35,10 +35,13 @@ const PROJECT_CONTEXT_FILES: &[&str] = &[
 
 /// User-level project instructions loaded as a fallback when the workspace and
 /// its parents do not define project context. `.codewhale/` takes priority
-/// over `.deepseek/` for both WHALE.md and AGENTS.md.
+/// over vendor-neutral `.agents/`, which takes priority over legacy
+/// `.deepseek/`, for both WHALE.md and AGENTS.md.
 const GLOBAL_AGENTS_RELATIVE_PATH: &[&str] = &[".codewhale", "AGENTS.md"];
+const GLOBAL_AGENTS_VENDOR_NEUTRAL_PATH: &[&str] = &[".agents", "AGENTS.md"];
 const GLOBAL_AGENTS_LEGACY_PATH: &[&str] = &[".deepseek", "AGENTS.md"];
 const GLOBAL_WHALE_RELATIVE_PATH: &[&str] = &[".codewhale", "WHALE.md"];
+const GLOBAL_WHALE_VENDOR_NEUTRAL_PATH: &[&str] = &[".agents", "WHALE.md"];
 const GLOBAL_WHALE_LEGACY_PATH: &[&str] = &[".deepseek", "WHALE.md"];
 
 /// Maximum size for project context files (to prevent loading huge files)
@@ -50,6 +53,7 @@ const PACK_MAX_CONFIG_FILES: usize = 60;
 const PACK_MAX_DEPTH: usize = 4;
 const PACK_IGNORED_DIRS: &[&str] = &[
     ".git",
+    ".worktrees",
     "node_modules",
     ".venv",
     "venv",
@@ -384,6 +388,11 @@ pub fn load_project_context(workspace: &Path) -> ProjectContext {
         if file_path.exists() && file_path.is_file() {
             match load_context_file(&file_path) {
                 Ok(content) => {
+                    tracing::info!(
+                        "Loaded project context from {} ({} bytes)",
+                        file_path.display(),
+                        content.len()
+                    );
                     ctx.instructions = Some(content);
                     ctx.source_path = Some(file_path);
                     break;
@@ -431,7 +440,7 @@ fn load_project_context_with_parents_and_home(
         }
     }
 
-    // Always check `~/.deepseek/AGENTS.md` so user-wide preferences
+    // Always check global instruction files so user-wide preferences
     // travel into every session (#1157). When both global and project
     // instructions exist, the global block prepends the project's so
     // workspace overrides win the last word; when only global exists,
@@ -481,12 +490,11 @@ fn load_project_context_with_parents_and_home(
     ctx
 }
 
-/// Combine `~/.deepseek/AGENTS.md` (global, user-wide preferences) with a
-/// project-local AGENTS.md/CLAUDE.md/instructions.md. Global comes first
-/// so workspace-specific rules can override it — the model reads in
-/// declared order. Each block is wrapped in a labelled fence so the
-/// model can tell which level any rule comes from when the two sets
-/// disagree (#1157).
+/// Combine global user-wide preferences with a project-local
+/// AGENTS.md/CLAUDE.md/instructions.md. Global comes first so
+/// workspace-specific rules can override it — the model reads in declared
+/// order. Each block is wrapped in a labelled fence so the model can tell
+/// which level any rule comes from when the two sets disagree (#1157).
 fn merge_global_and_project_instructions(
     global: &str,
     global_source: Option<&Path>,
@@ -508,11 +516,15 @@ fn load_global_agents_context(workspace: &Path, home_dir: Option<&Path>) -> Opti
     // Priority order:
     // 1. ~/.codewhale/WHALE.md      (CodeWhale-native)
     // 2. ~/.codewhale/AGENTS.md     (new config directory)
-    // 3. ~/.deepseek/WHALE.md       (legacy fallback)
-    // 4. ~/.deepseek/AGENTS.md      (legacy fallback)
+    // 3. ~/.agents/WHALE.md         (vendor-neutral fallback)
+    // 4. ~/.agents/AGENTS.md        (vendor-neutral fallback)
+    // 5. ~/.deepseek/WHALE.md       (legacy fallback)
+    // 6. ~/.deepseek/AGENTS.md      (legacy fallback)
     let candidates: &[&[&str]] = &[
         GLOBAL_WHALE_RELATIVE_PATH,
         GLOBAL_AGENTS_RELATIVE_PATH,
+        GLOBAL_WHALE_VENDOR_NEUTRAL_PATH,
+        GLOBAL_AGENTS_VENDOR_NEUTRAL_PATH,
         GLOBAL_WHALE_LEGACY_PATH,
         GLOBAL_AGENTS_LEGACY_PATH,
     ];
@@ -1038,6 +1050,58 @@ mod tests {
         assert_eq!(ctx.source_path, Some(global_agents));
     }
 
+    #[test]
+    fn test_load_global_agents_falls_back_to_vendor_neutral_path() {
+        let workspace = tempdir().expect("workspace tempdir");
+        let home = tempdir().expect("home tempdir");
+        let global_dir = home.path().join(".agents");
+        fs::create_dir(&global_dir).expect("mkdir .agents");
+        let global_agents = global_dir.join("AGENTS.md");
+        fs::write(&global_agents, "Vendor-neutral instructions").expect("write global agents");
+
+        let ctx = load_project_context_with_parents_and_home(workspace.path(), Some(home.path()));
+
+        assert!(ctx.has_instructions());
+        assert!(
+            ctx.instructions
+                .as_ref()
+                .unwrap()
+                .contains("Vendor-neutral instructions")
+        );
+        assert_eq!(ctx.source_path, Some(global_agents));
+    }
+
+    #[test]
+    fn test_codewhale_specific_path_wins_over_agents_path() {
+        let workspace = tempdir().expect("workspace tempdir");
+        let home = tempdir().expect("home tempdir");
+
+        let codewhale_dir = home.path().join(".codewhale");
+        fs::create_dir(&codewhale_dir).expect("mkdir .codewhale");
+        let codewhale_agents = codewhale_dir.join("AGENTS.md");
+        fs::write(&codewhale_agents, "CodeWhale-specific instructions")
+            .expect("write codewhale agents");
+
+        let agents_dir = home.path().join(".agents");
+        fs::create_dir(&agents_dir).expect("mkdir .agents");
+        fs::write(agents_dir.join("AGENTS.md"), "Vendor-neutral instructions")
+            .expect("write vendor-neutral agents");
+
+        let ctx = load_project_context_with_parents_and_home(workspace.path(), Some(home.path()));
+
+        assert!(ctx.has_instructions());
+        let instructions = ctx.instructions.as_ref().unwrap();
+        assert!(
+            instructions.contains("CodeWhale-specific instructions"),
+            "CodeWhale-specific global file should win:\n{instructions}"
+        );
+        assert!(
+            !instructions.contains("Vendor-neutral instructions"),
+            "lower-priority .agents file should be skipped:\n{instructions}"
+        );
+        assert_eq!(ctx.source_path, Some(codewhale_agents));
+    }
+
     #[test]
     fn test_local_and_global_agents_merge_when_both_exist() {
         // #1157: when both `~/.deepseek/AGENTS.md` and a project AGENTS.md
diff --git a/crates/tui/src/prompts.rs b/crates/tui/src/prompts.rs
index aa69f4f7..3f9475ee 100644
--- a/crates/tui/src/prompts.rs
+++ b/crates/tui/src/prompts.rs
@@ -2,7 +2,7 @@
 //! System prompts for different modes.
 //!
 //! Prompts are assembled from composable layers loaded at compile time:
-//!   base.md → personality overlay → mode delta → approval policy
+//!   tool taxonomy → base.md → personality overlay → mode delta → approval policy
 //!
 //! This keeps each concern in its own file and makes prompt tuning
 //! a single-file operation.
@@ -34,6 +34,10 @@ pub struct PromptSessionContext<'a> {
     /// preserving backward compatibility with existing call sites
     /// that predate dynamic model injection.
     pub model_id: &'a str,
+    /// Whether the user-visible transcript renders thinking blocks.
+    /// When false, the prompt should not spend localization pressure on
+    /// `reasoning_content` the user will never see.
+    pub show_thinking: bool,
 }
 
 impl Default for PromptSessionContext<'_> {
@@ -45,6 +49,7 @@ impl Default for PromptSessionContext<'_> {
             locale_tag: "en",
             translation_enabled: false,
             model_id: "codewhale",
+            show_thinking: true,
         }
     }
 }
@@ -53,7 +58,9 @@ impl Default for PromptSessionContext<'_> {
 /// A previous session writes it on exit / `/compact`; the next session reads
 /// it back on startup and prepends it to the system prompt so a fresh agent
 /// doesn't have to re-discover open blockers from scratch.
-pub const HANDOFF_RELATIVE_PATH: &str = ".deepseek/handoff.md";
+pub const HANDOFF_RELATIVE_PATH: &str = ".codewhale/handoff.md";
+/// Legacy handoff path for reading from existing installs.
+const LEGACY_HANDOFF_RELATIVE_PATH: &str = ".deepseek/handoff.md";
 
 /// Per-file size cap for `instructions = [...]` entries (#454). Mirrors
 /// the existing project-context cap in `project_context::load_context_file`
@@ -99,11 +106,32 @@ fn translation_target_language_for_tag(locale_tag: &str) -> &'static str {
         "Simplified Chinese (简体中文)"
     } else if normalized.starts_with("pt") {
         "Brazilian Portuguese (Português do Brasil)"
+    } else if normalized.starts_with("vi") {
+        "Vietnamese (Tiếng Việt)"
     } else {
         "English"
     }
 }
 
+fn hidden_thinking_language_instruction(locale_tag: &str) -> String {
+    let fallback_language = translation_target_language_for_tag(locale_tag);
+    format!(
+        "\
+## Hidden Thinking Language\n\
+\n\
+The user has disabled thinking display (`show_thinking = false`). If you emit \
+`reasoning_content`, keep that hidden internal thinking in English regardless \
+of the latest user-message language or `## Environment.lang`; the user will \
+not see it, so localizing hidden thinking only adds language switching.\n\
+\n\
+The final reply is still user-visible. Follow the normal `## Language` rule \
+for the final reply: mirror the latest user message, and use \
+{fallback_language} only when the user message is ambiguous. If the user \
+explicitly asks for a different thinking language, follow that explicit request \
+for the current turn."
+    )
+}
+
 /// Render a `## Environment` block listing the resolved locale tag,
 /// runtime version, host platform, login shell, and current working directory.
 ///
@@ -116,7 +144,10 @@ fn translation_target_language_for_tag(locale_tag: &str) -> &'static str {
 fn render_environment_block(workspace: &Path, locale_tag: &str) -> String {
     let deepseek_version = env!("CARGO_PKG_VERSION");
     let platform = std::env::consts::OS;
-    let shell = std::env::var("SHELL").unwrap_or_else(|_| "unknown".to_string());
+    let shell = crate::shell_dispatcher::global_dispatcher()
+        .kind()
+        .binary()
+        .to_string();
     let pwd = workspace.display();
 
     format!(
@@ -130,44 +161,88 @@ fn render_environment_block(workspace: &Path, locale_tag: &str) -> String {
     )
 }
 
+/// Source for an `EngineConfig.instructions` entry. Either a disk file (loaded
+/// at render time, original semantics) or an inline string (content baked into
+/// `EngineConfig`, no disk I/O at render time).
+///
+/// The inline variant is useful for embedders that compute instructions at
+/// runtime (e.g. rendering a template with workspace-specific substitutions)
+/// and don't want to stage the content to a disk file just to satisfy a path
+/// API. Staging adds two problems the inline path avoids:
+///
+///   1. The disk file looks like editable config but gets overwritten on
+///      every launch — confusing for users browsing the install dir.
+///   2. Multi-engine setups need per-engine paths to avoid `rehydrate`
+///      reading another session's instructions; with inline sources the
+///      content lives in the per-engine `EngineConfig` and the race
+///      surface goes away.
+///
+/// `From<PathBuf>` is provided so existing callers passing `Vec<PathBuf>` can
+/// keep working with a `.into()` upgrade at the call site.
+#[derive(Debug, Clone)]
+pub enum InstructionSource {
+    /// Load this file from disk at prompt-render time. Original behavior:
+    /// missing files are skipped with a warning, oversized files are
+    /// truncated to `INSTRUCTIONS_FILE_MAX_BYTES` with an `[…elided]`
+    /// marker.
+    File(PathBuf),
+    /// Use the provided string directly. `name` becomes the
+    /// `<instructions source="…">` attribute (typically a synthetic
+    /// identifier like `embedded:my-template` or a logical path).
+    Inline { name: String, content: String },
+}
+
+impl From<PathBuf> for InstructionSource {
+    fn from(path: PathBuf) -> Self {
+        InstructionSource::File(path)
+    }
+}
+
+impl From<&PathBuf> for InstructionSource {
+    fn from(path: &PathBuf) -> Self {
+        InstructionSource::File(path.clone())
+    }
+}
+
 /// Render the `instructions = [...]` config array as a single
-/// system-prompt block (#454). Each path is loaded in declared order;
-/// missing files are skipped with a tracing warning so a stale entry
-/// in `~/.deepseek/config.toml` doesn't fail the launch. Empty input
-/// (or all paths missing) returns `None` so callers append nothing.
-fn render_instructions_block(paths: &[PathBuf]) -> Option<String> {
+/// system-prompt block (#454). Each source is processed in declared order;
+/// missing `File` sources are skipped with a tracing warning so a stale entry
+/// doesn't fail the launch. Empty input (or all sources missing/empty)
+/// returns `None` so callers append nothing.
+fn render_instructions_block(sources: &[InstructionSource]) -> Option<String> {
     let mut sections: Vec<String> = Vec::new();
-    for path in paths {
-        match std::fs::read_to_string(path) {
-            Ok(raw) => {
-                let trimmed = raw.trim();
-                if trimmed.is_empty() {
+    for source in sources {
+        let (raw_source_name, raw_content): (String, String) = match source {
+            InstructionSource::File(path) => match std::fs::read_to_string(path) {
+                Ok(raw) => (path.display().to_string(), raw),
+                Err(err) => {
+                    tracing::warn!(
+                        target: "instructions",
+                        ?err,
+                        ?path,
+                        "skipping unreadable instructions file"
+                    );
                     continue;
                 }
-                let body = if trimmed.len() > INSTRUCTIONS_FILE_MAX_BYTES {
-                    let head_end = (0..=INSTRUCTIONS_FILE_MAX_BYTES)
-                        .rev()
-                        .find(|&i| trimmed.is_char_boundary(i))
-                        .unwrap_or(0);
-                    format!("{}\n[…elided]", &trimmed[..head_end])
-                } else {
-                    trimmed.to_string()
-                };
-                sections.push(format!(
-                    "<instructions source=\"{}\">\n{}\n</instructions>",
-                    path.display(),
-                    body
-                ));
-            }
-            Err(err) => {
-                tracing::warn!(
-                    target: "instructions",
-                    ?err,
-                    ?path,
-                    "skipping unreadable instructions file"
-                );
-            }
+            },
+            InstructionSource::Inline { name, content } => (name.clone(), content.clone()),
+        };
+        let trimmed = raw_content.trim();
+        if trimmed.is_empty() {
+            continue;
         }
+        let body = if trimmed.len() > INSTRUCTIONS_FILE_MAX_BYTES {
+            let head_end = (0..=INSTRUCTIONS_FILE_MAX_BYTES)
+                .rev()
+                .find(|&i| trimmed.is_char_boundary(i))
+                .unwrap_or(0);
+            format!("{}\n[…elided]", &trimmed[..head_end])
+        } else {
+            trimmed.to_string()
+        };
+        sections.push(format!(
+            "<instructions source=\"{raw_source_name}\">\n{body}\n</instructions>"
+        ));
     }
     if sections.is_empty() {
         None
@@ -180,7 +255,12 @@ fn render_instructions_block(paths: &[PathBuf]) -> Option<String> {
 /// system-prompt block. Returns `None` when the file is absent or empty so
 /// callers can keep the default-uncluttered prompt for fresh workspaces.
 fn load_handoff_block(workspace: &Path) -> Option<String> {
-    let path = workspace.join(HANDOFF_RELATIVE_PATH);
+    let primary = workspace.join(HANDOFF_RELATIVE_PATH);
+    let path = if primary.exists() {
+        primary
+    } else {
+        workspace.join(LEGACY_HANDOFF_RELATIVE_PATH)
+    };
     let raw = std::fs::read_to_string(&path).ok()?;
     let trimmed = raw.trim();
     if trimmed.is_empty() {
@@ -197,6 +277,126 @@ fn load_handoff_block(workspace: &Path) -> Option<String> {
 /// "When NOT to use" guidance, sub-agent sentinel protocol.
 pub const BASE_PROMPT: &str = include_str!("prompts/base.md");
 
+// ── Embedder prompt overrides ──
+// Let an embedder replace these compile-time prompt constants at startup,
+// so brand / slimming customizations live in the embedder crate instead of
+// editing these files in-tree. Unset → the bundled constant (fully
+// backward compatible). Intended to be set once at process start, before
+// any engine spawns; later sets return the rejected override string.
+static BASE_PROMPT_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_PREAMBLE_ZH_HANS_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_PREAMBLE_JA_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_PREAMBLE_PT_BR_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_PREAMBLE_VI_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_CLOSER_ZH_HANS_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_CLOSER_JA_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_CLOSER_PT_BR_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static LOCALE_CLOSER_VI_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+static AUTHORITY_RECAP_OVERRIDE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+
+/// Replace `BASE_PROMPT` for all subsequent prompt composition. First call
+/// wins; later calls return the rejected string. Set before spawning any
+/// engine.
+pub fn set_base_prompt_override(s: String) -> Result<(), String> {
+    set_prompt_override(&BASE_PROMPT_OVERRIDE, s)
+}
+
+/// Replace the Simplified-Chinese locale preamble (`## 语言要求`).
+pub fn set_locale_preamble_zh_hans_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_PREAMBLE_ZH_HANS_OVERRIDE, s)
+}
+
+/// Replace the Japanese locale preamble.
+pub fn set_locale_preamble_ja_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_PREAMBLE_JA_OVERRIDE, s)
+}
+
+/// Replace the Brazilian-Portuguese locale preamble.
+pub fn set_locale_preamble_pt_br_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_PREAMBLE_PT_BR_OVERRIDE, s)
+}
+
+/// Replace the Vietnamese locale preamble.
+pub fn set_locale_preamble_vi_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_PREAMBLE_VI_OVERRIDE, s)
+}
+
+/// Replace the Simplified-Chinese locale closer (`## 语言再次提醒`).
+pub fn set_locale_closer_zh_hans_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_CLOSER_ZH_HANS_OVERRIDE, s)
+}
+
+/// Replace the Japanese locale closer.
+pub fn set_locale_closer_ja_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_CLOSER_JA_OVERRIDE, s)
+}
+
+/// Replace the Brazilian-Portuguese locale closer.
+pub fn set_locale_closer_pt_br_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_CLOSER_PT_BR_OVERRIDE, s)
+}
+
+/// Replace the Vietnamese locale closer.
+pub fn set_locale_closer_vi_override(s: String) -> Result<(), String> {
+    set_prompt_override(&LOCALE_CLOSER_VI_OVERRIDE, s)
+}
+
+/// Replace the trailing `## Authority Recap` block.
+pub fn set_authority_recap_override(s: String) -> Result<(), String> {
+    set_prompt_override(&AUTHORITY_RECAP_OVERRIDE, s)
+}
+
+fn set_prompt_override(cell: &std::sync::OnceLock<String>, s: String) -> Result<(), String> {
+    cell.set(s)
+}
+
+fn effective_prompt_override<'a>(
+    cell: &'a std::sync::OnceLock<String>,
+    fallback: &'static str,
+) -> &'a str {
+    cell.get().map(String::as_str).unwrap_or(fallback)
+}
+
+fn effective_base_prompt() -> &'static str {
+    effective_prompt_override(&BASE_PROMPT_OVERRIDE, BASE_PROMPT)
+}
+
+fn effective_locale_preamble_zh_hans() -> &'static str {
+    effective_prompt_override(&LOCALE_PREAMBLE_ZH_HANS_OVERRIDE, LOCALE_PREAMBLE_ZH_HANS)
+}
+
+fn effective_locale_preamble_ja() -> &'static str {
+    effective_prompt_override(&LOCALE_PREAMBLE_JA_OVERRIDE, LOCALE_PREAMBLE_JA)
+}
+
+fn effective_locale_preamble_pt_br() -> &'static str {
+    effective_prompt_override(&LOCALE_PREAMBLE_PT_BR_OVERRIDE, LOCALE_PREAMBLE_PT_BR)
+}
+
+fn effective_locale_preamble_vi() -> &'static str {
+    effective_prompt_override(&LOCALE_PREAMBLE_VI_OVERRIDE, LOCALE_PREAMBLE_VI)
+}
+
+fn effective_locale_closer_zh_hans() -> &'static str {
+    effective_prompt_override(&LOCALE_CLOSER_ZH_HANS_OVERRIDE, LOCALE_CLOSER_ZH_HANS)
+}
+
+fn effective_locale_closer_ja() -> &'static str {
+    effective_prompt_override(&LOCALE_CLOSER_JA_OVERRIDE, LOCALE_CLOSER_JA)
+}
+
+fn effective_locale_closer_pt_br() -> &'static str {
+    effective_prompt_override(&LOCALE_CLOSER_PT_BR_OVERRIDE, LOCALE_CLOSER_PT_BR)
+}
+
+fn effective_locale_closer_vi() -> &'static str {
+    effective_prompt_override(&LOCALE_CLOSER_VI_OVERRIDE, LOCALE_CLOSER_VI)
+}
+
+fn effective_authority_recap() -> &'static str {
+    effective_prompt_override(&AUTHORITY_RECAP_OVERRIDE, AUTHORITY_RECAP)
+}
+
 /// Optional locale-native reinforcement preamble prepended to the system
 /// prompt when the user's UI locale is non-English.
 ///
@@ -262,9 +462,10 @@ pub const BASE_PROMPT: &str = include_str!("prompts/base.md");
 /// and the closer position would all carry over unchanged.
 pub(crate) fn locale_reinforcement_preamble(locale_tag: &str) -> Option<&'static str> {
     match locale_tag {
-        "zh-Hans" | "zh-CN" | "zh" => Some(LOCALE_PREAMBLE_ZH_HANS),
-        "ja" | "ja-JP" => Some(LOCALE_PREAMBLE_JA),
-        "pt-BR" | "pt" => Some(LOCALE_PREAMBLE_PT_BR),
+        "zh-Hans" | "zh-CN" | "zh" => Some(effective_locale_preamble_zh_hans()),
+        "ja" | "ja-JP" => Some(effective_locale_preamble_ja()),
+        "pt-BR" | "pt" => Some(effective_locale_preamble_pt_br()),
+        "vi" | "vi-VN" => Some(effective_locale_preamble_vi()),
         _ => None,
     }
 }
@@ -287,9 +488,10 @@ pub(crate) fn locale_reinforcement_preamble(locale_tag: &str) -> Option<&'static
 /// behavior.
 pub(crate) fn locale_reinforcement_closer(locale_tag: &str) -> Option<&'static str> {
     match locale_tag {
-        "zh-Hans" | "zh-CN" | "zh" => Some(LOCALE_CLOSER_ZH_HANS),
-        "ja" | "ja-JP" => Some(LOCALE_CLOSER_JA),
-        "pt-BR" | "pt" => Some(LOCALE_CLOSER_PT_BR),
+        "zh-Hans" | "zh-CN" | "zh" => Some(effective_locale_closer_zh_hans()),
+        "ja" | "ja-JP" => Some(effective_locale_closer_ja()),
+        "pt-BR" | "pt" => Some(effective_locale_closer_pt_br()),
+        "vi" | "vi-VN" => Some(effective_locale_closer_vi()),
         _ => None,
     }
 }
@@ -357,6 +559,24 @@ idioma. A menos que o usuário peça explicitamente a troca (por exemplo, \
 \"think in English\"), continue pensando e respondendo em português do \
 Brasil.";
 
+const LOCALE_PREAMBLE_VI: &str = "## Yêu cầu ngôn ngữ\n\n\
+Bạn đang chạy trong codewhale. Cho dù ngữ cảnh tác vụ (mã nguồn, nhật ký lỗi, tên tệp) \
+là tiếng Anh, cho dù phần còn lại của system prompt là tiếng Anh, bạn đều phải sử dụng \
+tiếng Việt cho phần `reasoning_content` (suy nghĩ nội bộ) và câu trả lời cuối cùng. Các từ \
+mã nguồn, đường dẫn tệp, tên công cụ (ví dụ `read_file`, `exec_shell`), biến môi trường, \
+tham số dòng lệnh và URL giữ nguyên dạng gốc —— chỉ các văn bản giải thích bằng ngôn ngữ \
+tự nhiên mới được chuyển sang tiếng Việt.\n\n\
+Nếu người dùng chuyển sang ngôn ngữ khác trong phiên làm việc, hãy chuyển theo từ lượt tiếp theo. \
+Nếu người dùng yêu cầu rõ ràng (ví dụ \"think in English\"), hãy ghi đè quy tắc này.";
+
+const LOCALE_CLOSER_VI: &str = "## Nhắc nhở ngôn ngữ một lần nữa\n\n\
+**Quan trọng: phần `reasoning_content` (suy nghĩ nội bộ) và phản hồi cuối cùng của bạn phải được viết bằng tiếng Việt.** \
+Dù bạn có đọc bao nhiêu mã nguồn tiếng Anh, nhật ký lỗi hay tài liệu trong phiên làm việc này, và dù ngữ cảnh \
+dự án có là tiếng Anh, quá trình suy nghĩ của bạn cũng không được chuyển sang tiếng Anh. Đây là yêu cầu cứng \
+ở cấp phiên làm việc —— ngôn ngữ của người dùng quyết định ngôn ngữ của bạn, không phụ thuộc vào nội dung tiếng Anh \
+tích lũy trong ngữ cảnh. Trừ khi người dùng yêu cầu rõ ràng việc chuyển đổi (ví dụ \"think in English\"), \
+hãy tiếp tục suy nghĩ và trả lời bằng tiếng Việt.";
+
 /// Personality overlays — voice and tone.
 pub const CALM_PERSONALITY: &str = include_str!("prompts/personalities/calm.md");
 pub const PLAYFUL_PERSONALITY: &str = include_str!("prompts/personalities/playful.md");
@@ -373,9 +593,13 @@ pub const SUGGEST_APPROVAL: &str = include_str!("prompts/approvals/suggest.md");
 pub const NEVER_APPROVAL: &str = include_str!("prompts/approvals/never.md");
 
 /// Compaction relay template — written into the system prompt so the
-/// model knows the format to use when writing `.deepseek/handoff.md`.
+/// model knows the format to use when writing `.codewhale/handoff.md`.
 pub const COMPACT_TEMPLATE: &str = include_str!("prompts/compact.md");
 
+/// Goal continuation audit template — injected by the engine when a runtime
+/// goal is active and the assistant tries to end a turn without closing it.
+pub const GOAL_CONTINUATION_PROMPT: &str = include_str!("prompts/continuation.md");
+
 /// Memory hygiene guidance — appended to the system prompt only when the
 /// session has a non-empty user-memory block. Steers the model toward
 /// writing durable memories as declarative facts ("User prefers concise
@@ -455,10 +679,11 @@ fn approval_prompt_for_mode(mode: AppMode, approval_mode: ApprovalMode) -> &'sta
 }
 
 /// Compose the full system prompt in deterministic order:
-///   1. base.md        — core identity, toolbox, execution contract
-///   2. personality    — voice and tone overlay
-///   3. mode delta     — mode-specific permissions and workflow
-///   4. approval policy — tool-approval behavior
+///   1. tool taxonomy  — compact hints generated from the eager core tools
+///   2. base.md        — core identity, toolbox, execution contract
+///   3. personality    — voice and tone overlay
+///   4. mode delta     — mode-specific permissions and workflow
+///   5. approval policy — tool-approval behavior
 ///
 /// Each layer is separated by a blank line for readability in the
 /// rendered prompt (the model sees them as contiguous sections).
@@ -471,6 +696,51 @@ fn apply_model_template(prompt: &str, model_id: &str) -> String {
     prompt.replace("{model_id}", model_id)
 }
 
+const TOOL_TAXONOMY_DISCOVERY: &[&str] = &["grep_files", "file_search"];
+const TOOL_TAXONOMY_GIT: &[&str] = &["git_status", "git_diff"];
+const TOOL_TAXONOMY_VERIFICATION: &[&str] = &["run_tests"];
+
+fn render_core_tool_taxonomy_block(mode: AppMode) -> String {
+    let core_tools = core_taxonomy_tools_for_mode(mode);
+    let mut sentences = Vec::new();
+
+    if let Some(discovery) = render_core_tool_group(TOOL_TAXONOMY_DISCOVERY, &core_tools) {
+        sentences.push(format!("Use {discovery} for discovery."));
+    }
+    if let Some(git) = render_core_tool_group(TOOL_TAXONOMY_GIT, &core_tools) {
+        sentences.push(format!("Use {git} for git inspection."));
+    }
+    if let Some(verification) = render_core_tool_group(TOOL_TAXONOMY_VERIFICATION, &core_tools) {
+        sentences.push(format!("Use {verification} for verification."));
+    }
+
+    debug_assert!(
+        !sentences.is_empty(),
+        "core tool taxonomy has no active tool groups"
+    );
+    format!("## Core Tool Taxonomy\n\n{}", sentences.join(" "))
+}
+
+fn core_taxonomy_tools_for_mode(mode: AppMode) -> Vec<&'static str> {
+    let core_tools = crate::core::engine::default_active_native_tool_names();
+    core_tools
+        .iter()
+        .copied()
+        .filter(|tool| mode != AppMode::Plan || *tool != "run_tests")
+        .collect()
+}
+
+fn render_core_tool_group(group: &[&str], core_tools: &[&str]) -> Option<String> {
+    let rendered = group
+        .iter()
+        .copied()
+        .filter(|tool| core_tools.contains(tool))
+        .map(|tool| format!("`{tool}`"))
+        .collect::<Vec<_>>()
+        .join("/");
+    (!rendered.is_empty()).then_some(rendered)
+}
+
 /// Authority recap block — appended at the end of the system prompt,
 /// just before the user's first message. Uses recency bias constructively:
 /// this is the last thing the model reads before generating, so it
@@ -506,8 +776,11 @@ pub fn compose_prompt_with_approval_and_model(
     approval_mode: ApprovalMode,
     model_id: &str,
 ) -> String {
-    let parts: [&str; 4] = [
-        &apply_model_template(BASE_PROMPT.trim(), model_id),
+    let tool_taxonomy = render_core_tool_taxonomy_block(mode);
+    let base_prompt = apply_model_template(effective_base_prompt().trim(), model_id);
+    let parts: [&str; 5] = [
+        tool_taxonomy.as_str(),
+        base_prompt.as_str(),
         personality.prompt().trim(),
         mode_prompt(mode).trim(),
         approval_prompt_for_mode(mode, approval_mode).trim(),
@@ -595,7 +868,7 @@ pub fn system_prompt_for_mode_with_context_and_skills(
     workspace: &Path,
     working_set_summary: Option<&str>,
     skills_dir: Option<&Path>,
-    instructions: Option<&[PathBuf]>,
+    instructions: Option<&[InstructionSource]>,
     user_memory_block: Option<&str>,
 ) -> SystemPrompt {
     system_prompt_for_mode_with_context_skills_and_session(
@@ -611,6 +884,7 @@ pub fn system_prompt_for_mode_with_context_and_skills(
             locale_tag: "en",
             translation_enabled: false,
             model_id: "codewhale",
+            show_thinking: true,
         },
     )
 }
@@ -620,7 +894,7 @@ pub fn system_prompt_for_mode_with_context_skills_and_session(
     workspace: &Path,
     _working_set_summary: Option<&str>,
     skills_dir: Option<&Path>,
-    instructions: Option<&[PathBuf]>,
+    instructions: Option<&[InstructionSource]>,
     session_context: PromptSessionContext<'_>,
 ) -> SystemPrompt {
     system_prompt_for_mode_with_context_skills_session_and_approval(
@@ -639,7 +913,7 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
     workspace: &Path,
     _working_set_summary: Option<&str>,
     skills_dir: Option<&Path>,
-    instructions: Option<&[PathBuf]>,
+    instructions: Option<&[InstructionSource]>,
     session_context: PromptSessionContext<'_>,
     approval_mode: ApprovalMode,
 ) -> SystemPrompt {
@@ -657,7 +931,11 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
     // in English even though `lang: zh-Hans` is set" failure mode that
     // PR #1398 partially addressed. English (and unknown) locales get
     // `None` and keep the previous behavior unchanged.
-    let preamble = locale_reinforcement_preamble(session_context.locale_tag);
+    let preamble = if session_context.show_thinking {
+        locale_reinforcement_preamble(session_context.locale_tag)
+    } else {
+        None
+    };
 
     // 1–2. Mode prompt + project context.
     // `load_project_context_with_parents` auto-generates .codewhale/instructions.md
@@ -682,17 +960,6 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
         full_prompt = format!("{full_prompt}\n\n{pack}");
     }
 
-    // 2.25. Environment block — locale, platform, shell, pwd. All
-    // four inputs are session-stable (workspace path is fixed for
-    // the run; locale is loaded once by the caller; platform/shell
-    // come from process env). Inserted above skills so it remains in
-    // the workspace-static cache layer alongside the mode prompt and
-    // project context.
-    full_prompt = format!(
-        "{full_prompt}\n\n{}",
-        render_environment_block(workspace, session_context.locale_tag),
-    );
-
     // 2.3a. Translation output instruction — when enabled, instruct
     // the model to respond in the resolved session locale. Stays
     // above the volatile-content boundary because it's a per-session
@@ -741,7 +1008,7 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
     }
 
     // 5. Compaction relay template — so the model knows the format to use
-    //    when writing `.deepseek/handoff.md` on exit / `/compact`.
+    //    when writing `.codewhale/handoff.md` on exit / `/compact`.
     full_prompt.push_str("\n\n");
     full_prompt.push_str(COMPACT_TEMPLATE);
 
@@ -752,13 +1019,31 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
     // so DeepSeek's KV prefix cache can hit on the entire system prompt
     // regardless of per-session edits to memory, goals, or instructions.
 
+    // 6. Environment block — platform, shell, pwd, locale.
+    //
+    // Placed below the volatile-content boundary. The original comment claimed
+    // "workspace path is fixed for the run" → static-cacheable, which is true
+    // for the terminal use case (one process owns one workspace for its
+    // lifetime). It is **not** true for embedders that swap workspaces between
+    // sessions (the Op::SyncSession path, multi-engine pools, IDE
+    // integrations binding the engine to a per-tab workspace, etc.):
+    // `pwd` drifts session-to-session and drags the entire static prefix
+    // out of cache reuse. Moving the block below the volatile boundary keeps
+    // mode / project / skills / context-mgmt / compact-template byte-stable
+    // across sessions while preserving the pwd info the model needs for
+    // `exec_shell` and structured search tools.
+    full_prompt = format!(
+        "{full_prompt}\n\n{}",
+        render_environment_block(workspace, session_context.locale_tag),
+    );
+
     // 6a. Configured `instructions = [...]` files (#454). Loaded
     // and concatenated in declared order. Placed below the volatile boundary
     // because these files are workspace-scoped and may differ between
     // sessions; any edit to them would otherwise bust the prefix cache for
     // all subsequent static layers.
-    if let Some(paths) = instructions
-        && let Some(block) = render_instructions_block(paths)
+    if let Some(sources) = instructions
+        && let Some(block) = render_instructions_block(sources)
     {
         full_prompt = format!("{full_prompt}\n\n{block}");
     }
@@ -780,7 +1065,7 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
         && !goal_objective.trim().is_empty()
     {
         full_prompt = format!(
-            "{full_prompt}\n\n## Current Session Goal\n\n<session_goal>\n{}\n</session_goal>",
+            "{full_prompt}\n\n## Current Hunt\n\n<session_goal>\n{}\n</session_goal>",
             goal_objective.trim()
         );
     }
@@ -793,7 +1078,8 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
     // 7a. Authority recap — the final tier reminder before user messages.
     // Uses recency bias constructively: this is the last content the model
     // sees before the user's turn, reinforcing the Constitutional hierarchy.
-    full_prompt = format!("{full_prompt}\n\n{AUTHORITY_RECAP}");
+    let authority_recap = effective_authority_recap();
+    full_prompt = format!("{full_prompt}\n\n{authority_recap}");
 
     // 8. Locale-native closing reinforcement (#1118 follow-up #2). The
     // opening preamble alone wasn't enough — community feedback (the
@@ -806,8 +1092,17 @@ pub fn system_prompt_for_mode_with_context_skills_session_and_approval(
     // rule immediately before it generates `reasoning_content` for the
     // turn. English (and unknown) locales return `None` and the prompt
     // stays byte-identical to the pre-bookend behavior.
-    if let Some(closer) = locale_reinforcement_closer(session_context.locale_tag) {
+    if let Some(closer) = session_context
+        .show_thinking
+        .then(|| locale_reinforcement_closer(session_context.locale_tag))
+        .flatten()
+    {
         full_prompt = format!("{full_prompt}\n\n{closer}");
+    } else if !session_context.show_thinking {
+        full_prompt = format!(
+            "{full_prompt}\n\n{}",
+            hidden_thinking_language_instruction(session_context.locale_tag)
+        );
     }
 
     SystemPrompt::Text(full_prompt)
@@ -832,7 +1127,21 @@ mod tests {
 
     /// Discriminator unique to the injected relay block (not present in the
     /// agent prompt's own discussion of the convention).
-    const HANDOFF_BLOCK_MARKER: &str = "left a relay artifact at `.deepseek/handoff.md`";
+    const HANDOFF_BLOCK_MARKER: &str = "left a relay artifact at `.codewhale/handoff.md`";
+
+    #[test]
+    fn prompt_override_storage_reports_duplicate_sets() {
+        let cell = std::sync::OnceLock::new();
+
+        assert_eq!(effective_prompt_override(&cell, "fallback"), "fallback");
+        assert!(set_prompt_override(&cell, "first".to_string()).is_ok());
+        assert_eq!(effective_prompt_override(&cell, "fallback"), "first");
+        assert_eq!(
+            set_prompt_override(&cell, "second".to_string()),
+            Err("second".to_string())
+        );
+        assert_eq!(effective_prompt_override(&cell, "fallback"), "first");
+    }
 
     fn contains_cjk(text: &str) -> bool {
         text.chars().any(|ch| {
@@ -944,6 +1253,64 @@ mod tests {
         );
     }
 
+    #[test]
+    fn composed_prompt_starts_with_core_tool_taxonomy() {
+        let prompt = compose_prompt_with_approval_and_model(
+            AppMode::Agent,
+            Personality::Calm,
+            ApprovalMode::Suggest,
+            "deepseek-v4-pro",
+        );
+        let expected_taxonomy = render_core_tool_taxonomy_block(AppMode::Agent);
+
+        assert!(
+            prompt.starts_with(&expected_taxonomy),
+            "composed prompt should start with the compact generated tool taxonomy"
+        );
+    }
+
+    #[test]
+    fn plan_prompt_taxonomy_omits_run_tests() {
+        let prompt = compose_prompt_with_approval_and_model(
+            AppMode::Plan,
+            Personality::Calm,
+            ApprovalMode::Never,
+            "deepseek-v4-pro",
+        );
+        let expected_taxonomy = render_core_tool_taxonomy_block(AppMode::Plan);
+
+        assert!(
+            prompt.starts_with(&expected_taxonomy),
+            "Plan prompt should start with its mode-specific tool taxonomy"
+        );
+        assert!(
+            expected_taxonomy.contains("for discovery")
+                && expected_taxonomy.contains("for git inspection"),
+            "Plan taxonomy should keep read-only discovery and git guidance"
+        );
+        assert!(
+            !expected_taxonomy.contains("run_tests")
+                && !expected_taxonomy.contains("for verification")
+                && !expected_taxonomy.contains("Use  "),
+            "Plan taxonomy must not advertise unavailable verification tools: {expected_taxonomy:?}"
+        );
+    }
+
+    #[test]
+    fn core_tool_taxonomy_only_references_default_active_tools() {
+        let core_tools = crate::core::engine::default_active_native_tool_names();
+        for tool in TOOL_TAXONOMY_DISCOVERY
+            .iter()
+            .chain(TOOL_TAXONOMY_GIT)
+            .chain(TOOL_TAXONOMY_VERIFICATION)
+        {
+            assert!(
+                core_tools.contains(tool),
+                "tool taxonomy references {tool}, but it is not in the eager native-tool list"
+            );
+        }
+    }
+
     #[test]
     fn authority_recap_appears_in_full_prompt() {
         let tmp = tempdir().expect("tempdir");
@@ -1087,6 +1454,7 @@ mod tests {
                 locale_tag: "zh-Hans",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
             ApprovalMode::Suggest,
         ) {
@@ -1157,6 +1525,7 @@ mod tests {
                 locale_tag: "zh-Hans",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
             ApprovalMode::Suggest,
         ) {
@@ -1184,6 +1553,58 @@ mod tests {
         );
     }
 
+    #[test]
+    fn hidden_thinking_uses_english_reasoning_without_locale_bookends() {
+        let tmp = tempdir().expect("tempdir");
+        let text = match system_prompt_for_mode_with_context_skills_session_and_approval(
+            AppMode::Agent,
+            tmp.path(),
+            None,
+            None,
+            None,
+            PromptSessionContext {
+                user_memory_block: None,
+                goal_objective: None,
+                project_context_pack_enabled: false,
+                locale_tag: "zh-Hans",
+                translation_enabled: false,
+                model_id: "codewhale",
+                show_thinking: false,
+            },
+            ApprovalMode::Suggest,
+        ) {
+            SystemPrompt::Text(text) => text,
+            SystemPrompt::Blocks(_) => panic!("expected text system prompt"),
+        };
+
+        assert!(
+            text.contains("## Hidden Thinking Language"),
+            "hidden thinking prompt must include the request-side language override"
+        );
+        assert!(
+            text.contains("reasoning_content") && text.contains("English"),
+            "hidden thinking override must steer reasoning_content to English"
+        );
+        assert!(
+            text.contains("final reply") && text.contains("Simplified Chinese"),
+            "hidden thinking override must preserve the visible reply language"
+        );
+        assert!(
+            !text.contains("## 语言要求") && !text.contains("## 语言再次提醒"),
+            "hidden thinking prompt must not also ask for localized reasoning"
+        );
+
+        let hidden_pos = text
+            .find("## Hidden Thinking Language")
+            .expect("hidden thinking block present");
+        let hidden_header_end = hidden_pos + "## Hidden Thinking Language".len();
+        let after_hidden_body = &text[hidden_header_end..];
+        assert!(
+            !after_hidden_body.contains("\n## "),
+            "hidden thinking override must be the final top-level block; got: {after_hidden_body:?}",
+        );
+    }
+
     #[test]
     fn system_prompt_skips_locale_preamble_for_english() {
         // English locale → no preamble injected. Asserts the
@@ -1202,6 +1623,7 @@ mod tests {
                 locale_tag: "en",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
             ApprovalMode::Suggest,
         ) {
@@ -1234,9 +1656,20 @@ mod tests {
             "English locale must not get a pt-BR closer: {text:?}"
         );
         assert!(
-            !contains_cjk(&text),
-            "English system prompt should avoid native-script priming tokens: {text:?}"
+            !contains_cjk(BASE_PROMPT),
+            "base prompt must not contain static CJK priming tokens"
         );
+        for mode in [AppMode::Agent, AppMode::Plan, AppMode::Yolo] {
+            let taxonomy = render_core_tool_taxonomy_block(mode);
+            assert!(
+                !contains_cjk(&taxonomy),
+                "tool taxonomy must not contain static CJK priming tokens: {taxonomy:?}"
+            );
+        }
+        // Do not assert on arbitrary CJK in the full system prompt: project
+        // context may legitimately contain localized file names, README text,
+        // or user-authored instructions. The locale bookend markers above are
+        // the priming tokens this test is meant to guard.
     }
 
     #[test]
@@ -1295,6 +1728,7 @@ mod tests {
                 locale_tag: "ja",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
         ) {
             SystemPrompt::Text(text) => text,
@@ -1331,6 +1765,7 @@ mod tests {
                 locale_tag: "en",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
         ) {
             SystemPrompt::Text(text) => text,
@@ -1359,6 +1794,7 @@ mod tests {
                 locale_tag: "en",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
         ) {
             SystemPrompt::Text(text) => text,
@@ -1416,6 +1852,7 @@ mod tests {
                 locale_tag: "en",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
         ) {
             SystemPrompt::Text(text) => text,
@@ -1444,6 +1881,7 @@ mod tests {
                 locale_tag: "en",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
         ) {
             SystemPrompt::Text(text) => text,
@@ -1639,6 +2077,7 @@ mod tests {
                 locale_tag: "en",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
         ) {
             SystemPrompt::Text(text) => text,
@@ -1673,6 +2112,7 @@ mod tests {
                 locale_tag: "en",
                 translation_enabled: false,
                 model_id: "codewhale",
+                show_thinking: true,
             },
         ) {
             SystemPrompt::Text(text) => text,
@@ -1680,7 +2120,7 @@ mod tests {
         };
 
         assert!(!prompt.contains("<session_goal>"));
-        assert!(!prompt.contains("## Current Session Goal"));
+        assert!(!prompt.contains("## Current Hunt"));
     }
 
     #[test]
@@ -1787,13 +2227,27 @@ mod tests {
         );
     }
 
+    /// Tier 5 Local Law must explicitly cover `EngineConfig.instructions`
+    /// files. Without this clause, embedders that inject instructions via the
+    /// config field (rather than via the four hard-coded path conventions)
+    /// get their files classified by path — and since those embedder-supplied
+    /// paths aren't `AGENTS.md` / `CLAUDE.md` / `.codewhale/instructions.md` /
+    /// `.deepseek/instructions.md`, the model defaults to treating their
+    /// imperatives as Tier 7 Memory (the lowest tier per Article VII),
+    /// overridable by a single user sentence.
+    #[test]
+    fn local_law_tier_covers_engine_config_instructions() {
+        let prompt = compose_prompt(AppMode::Agent, Personality::Calm);
+        assert!(
+            prompt.contains("any file configured via `EngineConfig.instructions`"),
+            "Tier 5 must explicitly cover EngineConfig.instructions so \
+             embedder-injected instructions are not default-classified as Tier 7 Memory."
+        );
+    }
+
     #[test]
     fn workspace_orientation_guidance_present() {
         let prompt = compose_prompt(AppMode::Agent, Personality::Calm);
-        // Workspace orientation guidance is now distributed across the
-        // Constitutional preamble (project context loading) and the
-        // Local Law tier (AGENTS.md/instructions.md). Verify the
-        // key guidance anchors are still present.
         assert!(prompt.contains("AGENTS.md"));
         assert!(prompt.contains("Local Law"));
         assert!(
@@ -2035,7 +2489,8 @@ mod tests {
 
     #[test]
     fn render_instructions_block_returns_none_for_empty_input() {
-        assert!(super::render_instructions_block(&[]).is_none());
+        let empty: &[super::InstructionSource] = &[];
+        assert!(super::render_instructions_block(empty).is_none());
     }
 
     #[test]
@@ -2045,7 +2500,7 @@ mod tests {
         std::fs::write(&real, "real content here").unwrap();
         let bogus = tmp.path().join("does-not-exist.md");
 
-        let block = super::render_instructions_block(&[bogus.clone(), real.clone()])
+        let block = super::render_instructions_block(&[bogus.clone().into(), real.clone().into()])
             .expect("present file should produce a block");
         assert!(block.contains("real content here"));
         assert!(block.contains(&real.display().to_string()));
@@ -2061,7 +2516,7 @@ mod tests {
         std::fs::write(&a, "ALPHA_MARKER").unwrap();
         std::fs::write(&b, "BRAVO_MARKER").unwrap();
 
-        let block = super::render_instructions_block(&[a, b]).expect("non-empty");
+        let block = super::render_instructions_block(&[a.into(), b.into()]).expect("non-empty");
         let alpha_pos = block.find("ALPHA_MARKER").expect("alpha rendered");
         let bravo_pos = block.find("BRAVO_MARKER").expect("bravo rendered");
         assert!(
@@ -2078,7 +2533,8 @@ mod tests {
         std::fs::write(&empty, "   \n   \n").unwrap();
         std::fs::write(&real, "real content").unwrap();
 
-        let block = super::render_instructions_block(&[empty, real]).expect("non-empty");
+        let block =
+            super::render_instructions_block(&[empty.into(), real.into()]).expect("non-empty");
         // Empty file produces no `<instructions>` section, only the real one.
         let count = block.matches("<instructions").count();
         assert_eq!(count, 1, "only the non-empty file should produce a section");
@@ -2091,7 +2547,7 @@ mod tests {
         // 200 KiB of content — well above the 100 KiB cap.
         std::fs::write(&big, "X".repeat(200 * 1024)).unwrap();
 
-        let block = super::render_instructions_block(&[big]).expect("non-empty");
+        let block = super::render_instructions_block(&[big.into()]).expect("non-empty");
         assert!(block.contains("[…elided]"), "truncation marker missing");
         // Block should be much smaller than the original file.
         assert!(
@@ -2100,6 +2556,51 @@ mod tests {
         );
     }
 
+    /// `InstructionSource::Inline` bypasses disk reads — the content is used
+    /// directly and `name` becomes the `<instructions source="…">` attribute.
+    /// Empty / oversize handling mirrors `File` variant.
+    #[test]
+    fn render_instructions_block_handles_inline_source() {
+        let block = super::render_instructions_block(&[super::InstructionSource::Inline {
+            name: "embedded:test/template".to_string(),
+            content: "INLINE_MARKER_CONTENT".to_string(),
+        }])
+        .expect("non-empty");
+        assert!(block.contains("INLINE_MARKER_CONTENT"));
+        assert!(block.contains("source=\"embedded:test/template\""));
+
+        // Empty inline → skipped just like empty file.
+        let empty_inline = super::InstructionSource::Inline {
+            name: "empty".to_string(),
+            content: "   ".to_string(),
+        };
+        assert!(super::render_instructions_block(&[empty_inline]).is_none());
+
+        // Oversize inline → truncated with elided marker.
+        let big_inline = super::InstructionSource::Inline {
+            name: "huge".to_string(),
+            content: "Y".repeat(200 * 1024),
+        };
+        let trimmed = super::render_instructions_block(&[big_inline]).expect("non-empty");
+        assert!(trimmed.contains("[…elided]"));
+
+        // File + Inline 混用,顺序保持。
+        let tmp = tempdir().expect("tempdir");
+        let file_path = tmp.path().join("file-first.md");
+        std::fs::write(&file_path, "FILE_MARKER").unwrap();
+        let mixed = super::render_instructions_block(&[
+            file_path.into(),
+            super::InstructionSource::Inline {
+                name: "inline-second".to_string(),
+                content: "INLINE_MARKER".to_string(),
+            },
+        ])
+        .expect("non-empty");
+        let file_pos = mixed.find("FILE_MARKER").expect("file rendered");
+        let inline_pos = mixed.find("INLINE_MARKER").expect("inline rendered");
+        assert!(file_pos < inline_pos, "声明顺序必须保留(File then Inline)");
+    }
+
     #[test]
     fn instructions_block_appears_in_system_prompt_when_configured() {
         let tmp = tempdir().expect("tempdir");
@@ -2107,12 +2608,13 @@ mod tests {
         let extra = workspace.join("extra-instructions.md");
         std::fs::write(&extra, "EXTRA_INSTRUCTIONS_MARKER_BODY").unwrap();
 
+        let extra_source: super::InstructionSource = extra.clone().into();
         let prompt = match super::system_prompt_for_mode_with_context_and_skills(
             AppMode::Agent,
             workspace,
             None,
             None,
-            Some(std::slice::from_ref(&extra)),
+            Some(std::slice::from_ref(&extra_source)),
             None,
         ) {
             SystemPrompt::Text(text) => text,
diff --git a/crates/tui/src/prompts/base.md b/crates/tui/src/prompts/base.md
index 83049925..061ff92c 100644
--- a/crates/tui/src/prompts/base.md
+++ b/crates/tui/src/prompts/base.md
@@ -52,7 +52,7 @@ When directives from different sources conflict, resolve in this order:
 
 4. **Regulations.** Composition patterns, sub-agent strategy, language rules, thinking budget. Best-practice guidance that yields to user intent when the two conflict.
 
-5. **Local Law.** Project instructions — AGENTS.md, CLAUDE.md, `.codewhale/instructions.md`, `.deepseek/instructions.md`. Project-specific rules that are subordinate to all higher tiers.
+5. **Local Law.** Project instructions — AGENTS.md, CLAUDE.md, `.codewhale/instructions.md`, `.deepseek/instructions.md`, **and any file configured via `EngineConfig.instructions` (rendered as `<instructions source="…">` blocks above)**. Project-specific rules that are subordinate to all higher tiers but supersede Memory (Tier 7), even when written in imperative voice — `EngineConfig.instructions` files are declared by the embedder (not user-collected like memory), so their imperatives are Local Law, not Memory preferences.
 
 6. **Evidence.** Tool output, file contents, command results, live repository state. Evidence is truth. Never contradict verified tool output. If memory and evidence conflict, evidence wins.
 
diff --git a/crates/tui/src/prompts/continuation.md b/crates/tui/src/prompts/continuation.md
new file mode 100644
index 00000000..492cb1a6
--- /dev/null
+++ b/crates/tui/src/prompts/continuation.md
@@ -0,0 +1,19 @@
+## Goal Continuation
+
+You are working toward an active session goal. Your task now is to make concrete
+progress toward the objective and audit whether the full goal is complete.
+
+Completion is unproven until you verify it against current-state evidence:
+
+1. Derive the concrete requirements from the goal and the latest user
+   instructions.
+2. Inspect authoritative evidence for each requirement: files, command output,
+   tests, runtime behavior, issue or PR state, rendered artifacts, or other
+   current sources.
+3. Treat uncertain or indirect evidence as not complete. Continue work or gather
+   stronger evidence.
+4. Only when the full objective is satisfied, call `update_goal` with
+   `status: "complete"` and concise evidence.
+
+If the goal cannot continue because of a real blocker, call `update_goal` with
+`status: "blocked"` and explain the blocker. Otherwise continue making progress.
diff --git a/crates/tui/src/purge.rs b/crates/tui/src/purge.rs
new file mode 100644
index 00000000..c7e09c68
--- /dev/null
+++ b/crates/tui/src/purge.rs
@@ -0,0 +1,920 @@
+//! Agent-driven context purging.
+//!
+//! Unlike compaction (which summarises old messages via LLM), purge lets the
+//! agent analyse the conversation history and surgically remove or rewrite
+//! individual messages that are no longer needed. The agent uses the
+//! `purge_context` tool to submit a list of operations; the engine validates
+//! and executes them.
+
+use regex::Regex;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Write;
+use tokio::sync::mpsc::Sender;
+
+use crate::core::events::Event;
+use crate::llm_client::LlmClient;
+use crate::models::{ContentBlock, Message, MessageRequest, Tool};
+
+// ── Prompt‑building constants ──────────────────────────────────────────────
+
+const TEXT_SNIPPET_CHARS: usize = 60;
+const TOOL_RESULT_SNIPPET_CHARS: usize = 80;
+const TOOL_USE_ARGS_CHARS: usize = 120;
+
+// ── Prompt instruction template ─────────────────────────────────────────────
+
+const PURGE_INSTRUCTIONS: &str = "\
+## Context Purge
+
+Free space in the conversation's context window. Below is the current history with stable numeric IDs.\
+Identify content that is clearly no longer needed for the ongoing work.
+
+### Operations
+
+remove  — Delete an entire message by its ID. Example:
+          {\"op\": \"remove\", \"msg\": 3}
+
+replace — Rewrite part of a specific content block using regex substitution.
+          pattern uses Rust regex syntax. Must specify both `block` and
+          `pattern` and `with`. Example:
+          {\"op\": \"replace\", \"msg\": 7, \"block\": 0,
+           \"pattern\": \"read \\\\d+ files\", \"with\": \"read files\"}
+
+### Pairing rule
+
+Every ToolUse block is paired with its ToolResult. If you remove a message
+containing a tool call, its result will be removed too — and vice versa. You
+do not need to list both.
+
+### What to keep
+
+- Important decisions, architectural choices
+- File paths that are still relevant
+- Tool outputs that contain information not yet acted upon
+
+### What to prune
+
+- Verbose tool outputs whose information has been fully consumed
+- Redundant confirmations (\"done\", \"ok\", \"that worked\")
+- Superseded file reads (the file was later written/modified)
+- Boilerplate that the model already incorporated into later work
+
+Be conservative. When in doubt, keep the message.
+
+### Conversation
+";
+
+// ── Purge operation types ───────────────────────────────────────────────────
+
+/// A single purge operation submitted by the agent.
+#[derive(Debug, Clone)]
+pub enum PurgeOp {
+    /// Remove an entire message (plus its tool-call/result counterpart).
+    Remove { msg_id: usize },
+    /// Regex-replace within a specific content block.
+    Replace {
+        msg_id: usize,
+        block_idx: usize,
+        pattern: Regex,
+        with: String,
+    },
+}
+
+/// Result of executing purge operations.
+#[derive(Debug, Clone)]
+pub struct PurgeResult {
+    /// The remaining messages after all operations.
+    pub messages: Vec<Message>,
+    /// How many messages were removed.
+    pub removed_count: usize,
+    /// How many replace operations were applied.
+    pub replaced_count: usize,
+}
+
+// ── Event emission helpers ──────────────────────────────────────────────────
+
+/// Emit a `PurgeStarted` event to the UI.
+pub async fn emit_purge_started(tx: &Sender<Event>, message: String) {
+    let _ = tx.send(Event::PurgeStarted { message }).await;
+}
+
+/// Emit a `PurgeCompleted` event to the UI.
+pub async fn emit_purge_completed(
+    tx: &Sender<Event>,
+    messages_before: usize,
+    messages_after: usize,
+    removed_count: usize,
+    replaced_count: usize,
+    message: String,
+) {
+    let _ = tx
+        .send(Event::PurgeCompleted {
+            messages_before,
+            messages_after,
+            removed_count,
+            replaced_count,
+            message,
+        })
+        .await;
+}
+
+/// Emit a `PurgeFailed` event to the UI.
+pub async fn emit_purge_failed(tx: &Sender<Event>, message: String) {
+    let _ = tx.send(Event::PurgeFailed { message }).await;
+}
+
+// ── Prompt builder ──────────────────────────────────────────────────────────
+
+/// Build the purge request user message — a formatted listing of the current
+/// conversation with ephemeral sequential IDs.
+pub fn build_purge_prompt(messages: &[Message]) -> String {
+    let mut buf = String::with_capacity(messages.len().saturating_mul(256));
+    buf.push_str(PURGE_INSTRUCTIONS);
+
+    for (idx, msg) in messages.iter().enumerate() {
+        let msg_id = idx + 1; // 1‑based for the agent
+        if msg.role == "user" {
+            // User messages: always a single block — omit block index.
+            format_user_message(&mut buf, msg_id, msg);
+        } else {
+            // Assistant messages: may be multi‑block — show block indices.
+            let _ = writeln!(buf, "[{msg_id}] {role}", role = msg.role);
+            for (blk_idx, block) in msg.content.iter().enumerate() {
+                format_content_block(&mut buf, blk_idx, block);
+            }
+            buf.push('\n');
+        }
+    }
+
+    buf
+}
+
+fn format_user_message(buf: &mut String, msg_id: usize, msg: &Message) {
+    let block = msg.content.first();
+    match block {
+        Some(ContentBlock::Text { text, .. }) => {
+            let snippet = truncate_str(text, TEXT_SNIPPET_CHARS);
+            let _ = writeln!(
+                buf,
+                "[{msg_id}] user  Text ({len} chars): \"{snippet}\"",
+                len = text.len()
+            );
+        }
+        Some(ContentBlock::ToolResult {
+            content,
+            tool_use_id,
+            ..
+        }) => {
+            let snippet = truncate_str(content, TOOL_RESULT_SNIPPET_CHARS);
+            let _ = writeln!(
+                buf,
+                "[{msg_id}] user  ToolResult (id={tool_use_id}, {len} chars): \"{snippet}\"",
+                len = content.len(),
+            );
+        }
+        _ => {
+            let _ = writeln!(buf, "[{msg_id}] user  (non‑text block)");
+        }
+    }
+}
+
+fn format_content_block(buf: &mut String, blk_idx: usize, block: &ContentBlock) {
+    match block {
+        ContentBlock::Text { text, .. } => {
+            let snippet = truncate_str(text, TEXT_SNIPPET_CHARS);
+            let _ = writeln!(
+                buf,
+                "  [{blk_idx}] Text ({len} chars): \"{snippet}\"",
+                len = text.len(),
+            );
+        }
+        ContentBlock::Thinking { .. } => {
+            // Omit thinking blocks — API-mandated on tool-call messages;
+            // the agent cannot remove them, so listing them only adds noise.
+        }
+        ContentBlock::ToolUse {
+            name, input, id, ..
+        } => {
+            let args = serde_json::to_string(input).unwrap_or_default();
+            let args_preview = truncate_str(&args, TOOL_USE_ARGS_CHARS);
+            let _ = writeln!(
+                buf,
+                "  [{blk_idx}] ToolUse ({name}, id={id}, args={args_preview})"
+            );
+        }
+        ContentBlock::ToolResult {
+            content,
+            tool_use_id,
+            ..
+        } => {
+            let snippet = truncate_str(content, TOOL_RESULT_SNIPPET_CHARS);
+            let _ = writeln!(
+                buf,
+                "  [{blk_idx}] ToolResult (id={tool_use_id}, {len} chars): \"{snippet}\"",
+                len = content.len(),
+            );
+        }
+        ContentBlock::ServerToolUse {
+            name, input, id, ..
+        } => {
+            let args = serde_json::to_string(input).unwrap_or_default();
+            let args_preview = truncate_str(&args, TOOL_USE_ARGS_CHARS);
+            let _ = writeln!(
+                buf,
+                "  [{blk_idx}] ServerToolUse ({name}, id={id}, args={args_preview})"
+            );
+        }
+        ContentBlock::ToolSearchToolResult {
+            tool_use_id,
+            content,
+            ..
+        } => {
+            let snippet = truncate_str(&content.to_string(), TOOL_RESULT_SNIPPET_CHARS);
+            let _ = writeln!(
+                buf,
+                "  [{blk_idx}] ToolSearchToolResult (id={tool_use_id}, content={snippet})"
+            );
+        }
+        ContentBlock::CodeExecutionToolResult {
+            tool_use_id,
+            content,
+            ..
+        } => {
+            let snippet = truncate_str(&content.to_string(), TOOL_RESULT_SNIPPET_CHARS);
+            let _ = writeln!(
+                buf,
+                "  [{blk_idx}] CodeExecutionToolResult (id={tool_use_id}, content={snippet})"
+            );
+        }
+    }
+}
+
+fn truncate_str(text: &str, max_chars: usize) -> String {
+    if text.chars().count() <= max_chars {
+        return text.to_string();
+    }
+    let take = max_chars.saturating_sub(3);
+    let mut out: String = text.chars().take(take).collect();
+    out.push_str("...");
+    out
+}
+
+// ── Operation parser ────────────────────────────────────────────────────────
+
+/// Parse the `purge_context` tool input JSON into a list of validated
+/// `PurgeOp`s. Returns an error string on invalid input.
+pub fn parse_purge_operations(
+    input: &serde_json::Value,
+    message_count: usize,
+) -> Result<Vec<PurgeOp>, String> {
+    let ops = input
+        .get("operations")
+        .and_then(|v| v.as_array())
+        .ok_or_else(|| "missing or invalid 'operations' array".to_string())?;
+
+    let mut parsed = Vec::with_capacity(ops.len());
+
+    for (i, op) in ops.iter().enumerate() {
+        let op_type = op
+            .get("op")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| format!("operation[{i}]: missing 'op' field"))?;
+
+        let msg = op
+            .get("msg")
+            .and_then(|v| v.as_u64())
+            .ok_or_else(|| format!("operation[{i}]: missing or invalid 'msg'"))?;
+
+        let msg_id = usize::try_from(msg).unwrap_or(usize::MAX);
+        if msg_id == 0 || msg_id > message_count {
+            return Err(format!(
+                "operation[{i}]: msg {msg} out of range (1–{message_count})"
+            ));
+        }
+
+        match op_type {
+            "remove" => {
+                parsed.push(PurgeOp::Remove { msg_id });
+            }
+            "replace" => {
+                let block_idx = op
+                    .get("block")
+                    .and_then(|v| v.as_u64())
+                    .map(|v| v as usize)
+                    .ok_or_else(|| format!("operation[{i}]: 'replace' requires 'block'"))?;
+
+                let pattern_str = op
+                    .get("pattern")
+                    .and_then(|v| v.as_str())
+                    .ok_or_else(|| format!("operation[{i}]: 'replace' requires 'pattern'"))?;
+
+                let with = op
+                    .get("with")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("")
+                    .to_string();
+
+                let pattern = Regex::new(pattern_str)
+                    .map_err(|e| format!("operation[{i}]: invalid regex pattern: {e}"))?;
+
+                parsed.push(PurgeOp::Replace {
+                    msg_id,
+                    block_idx,
+                    pattern,
+                    with,
+                });
+            }
+            other => {
+                return Err(format!(
+                    "operation[{i}]: unknown op '{other}' (expected 'remove' or 'replace')"
+                ));
+            }
+        }
+    }
+
+    Ok(parsed)
+}
+
+// ── Operation executor ──────────────────────────────────────────────────────
+
+/// Execute a list of purge operations against the message history.
+///
+/// Operations are processed in the order given but effective removal runs
+/// from highest index to lowest to keep earlier indices stable. After all
+/// user-requested operations, tool‑call/result pair cascading runs to
+/// prevent orphaned blocks.
+pub fn execute_purge_operations(messages: &[Message], ops: &[PurgeOp]) -> PurgeResult {
+    let mut msgs = messages.to_vec();
+    let mut msg_indices_to_remove: HashSet<usize> = HashSet::new();
+    let mut replaced_count = 0usize;
+
+    // Phase 1: collect removes and apply replaces.
+    for op in ops {
+        match op {
+            PurgeOp::Remove { msg_id } => {
+                let idx = msg_id.saturating_sub(1);
+                if idx < msgs.len() {
+                    msg_indices_to_remove.insert(idx);
+                }
+            }
+            PurgeOp::Replace {
+                msg_id,
+                block_idx,
+                pattern,
+                with,
+            } => {
+                let idx = msg_id.saturating_sub(1);
+                if idx >= msgs.len() {
+                    continue;
+                }
+                if let Some(block) = msgs[idx].content.get_mut(*block_idx) {
+                    let old_text = block_content_text(block).to_string();
+                    let new_text = pattern.replace_all(&old_text, with.as_str()).to_string();
+                    apply_block_replacement(block, &new_text);
+                    replaced_count = replaced_count.saturating_add(1);
+                }
+            }
+        }
+    }
+
+    // Phase 2: cascade removal to tool-call/result counterparts.
+    cascade_tool_pair_removals(&msgs, &mut msg_indices_to_remove);
+
+    // Phase 3: sort indices descending and remove.
+    let mut to_remove: Vec<usize> = msg_indices_to_remove.into_iter().collect();
+    to_remove.sort_unstable_by(|a, b| b.cmp(a));
+
+    let removed_count = to_remove.len();
+    for idx in to_remove {
+        msgs.remove(idx);
+    }
+
+    PurgeResult {
+        messages: msgs,
+        removed_count,
+        replaced_count,
+    }
+}
+
+/// When a message containing a ToolUse or ToolResult is marked for removal,
+/// cascade that removal to its counterpart so the API never sees orphaned
+/// blocks. Runs a fixpoint loop until the remove set is closed under pairing.
+fn cascade_tool_pair_removals(messages: &[Message], remove_set: &mut HashSet<usize>) {
+    if remove_set.is_empty() {
+        return;
+    }
+
+    // Build lookup maps: tool_use id → message index, tool_result id → message index.
+    let mut call_id_to_idx: HashMap<String, usize> = HashMap::new();
+    let mut result_id_to_idx: HashMap<String, usize> = HashMap::new();
+
+    for (idx, msg) in messages.iter().enumerate() {
+        for block in &msg.content {
+            match block {
+                ContentBlock::ToolUse { id, .. } => {
+                    call_id_to_idx.insert(id.clone(), idx);
+                }
+                ContentBlock::ToolResult { tool_use_id, .. } => {
+                    result_id_to_idx.insert(tool_use_id.clone(), idx);
+                }
+                _ => {}
+            }
+        }
+    }
+
+    // Fixpoint: when a tool-call is removed, also remove its result (and vice versa).
+    let max_iters = messages.len().max(10);
+    for _ in 0..max_iters {
+        let snapshot: Vec<usize> = remove_set.iter().copied().collect();
+        let mut changed = false;
+
+        for idx in snapshot {
+            let msg = &messages[idx];
+            for block in &msg.content {
+                match block {
+                    ContentBlock::ToolUse { id, .. } => {
+                        if let Some(&result_idx) = result_id_to_idx.get(id)
+                            && remove_set.insert(result_idx)
+                        {
+                            changed = true;
+                        }
+                    }
+                    ContentBlock::ToolResult { tool_use_id, .. } => {
+                        if let Some(&call_idx) = call_id_to_idx.get(tool_use_id)
+                            && remove_set.insert(call_idx)
+                        {
+                            changed = true;
+                        }
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        if !changed {
+            break;
+        }
+    }
+}
+
+fn block_content_text(block: &ContentBlock) -> &str {
+    match block {
+        ContentBlock::Text { text, .. } => text,
+        ContentBlock::ToolResult { content, .. } => content,
+        _ => "",
+    }
+}
+
+fn apply_block_replacement(block: &mut ContentBlock, new_text: &str) {
+    match block {
+        ContentBlock::Text { text, .. } => {
+            *text = new_text.to_string();
+        }
+        ContentBlock::ToolResult { content, .. } => {
+            *content = new_text.to_string();
+        }
+        _ => {}
+    }
+}
+
+// ── Tool definition builder ──────────────────────────────────────────────────
+
+/// Build the `purge_context` tool definition sent to the model during a purge
+/// turn. This tool is ad-hoc — it is not registered in the normal tool catalog
+/// and has no dispatch handler.
+pub fn build_purge_tool() -> Tool {
+    Tool {
+        tool_type: None,
+        name: "purge_context".to_string(),
+        description: "Remove or condense conversation history to free context window space."
+            .to_string(),
+        input_schema: serde_json::json!({
+            "type": "object",
+            "properties": {
+                "operations": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "op": {"type": "string", "enum": ["remove", "replace"]},
+                            "msg": {"type": "integer"},
+                            "block": {"type": "integer"},
+                            "pattern": {"type": "string"},
+                            "with": {"type": "string"}
+                        },
+                        "required": ["op", "msg"]
+                    }
+                }
+            },
+            "required": ["operations"]
+        }),
+        allowed_callers: None,
+        defer_loading: None,
+        input_examples: None,
+        strict: Some(true),
+        cache_control: None,
+    }
+}
+
+// ── Orchestration ────────────────────────────────────────────────────────────
+
+/// Run a full purge cycle: build the prompt, call the model with the
+/// `purge_context` tool, parse the response, and execute the operations.
+///
+/// Returns the `PurgeResult` with the modified message list on success,
+/// or a human-readable error string on failure.
+///
+/// Cost reporting is handled internally as a side-effect of the API call.
+/// The caller is responsible for emitting start/completed/failed events
+/// and for replacing the session message list with `PurgeResult.messages`.
+pub async fn run_purge(
+    client: &impl LlmClient,
+    messages: &[Message],
+    model: &str,
+    reasoning_effort: Option<String>,
+    max_tokens: u32,
+) -> Result<PurgeResult, String> {
+    // 1. Build the purge prompt from the current conversation.
+    let prompt = build_purge_prompt(messages);
+
+    // 2. Clone messages and inject the prompt as a user message.
+    let mut request_messages = messages.to_vec();
+    request_messages.push(Message {
+        role: "user".to_string(),
+        content: vec![ContentBlock::Text {
+            text: prompt,
+            cache_control: None,
+        }],
+    });
+
+    // 3. Build the tool definition and the request.
+    let purge_tool = build_purge_tool();
+    let request = MessageRequest {
+        model: model.to_string(),
+        messages: request_messages,
+        max_tokens,
+        system: None,
+        tools: Some(vec![purge_tool]),
+        tool_choice: None,
+        metadata: None,
+        thinking: None,
+        reasoning_effort,
+        stream: Some(false),
+        temperature: Some(0.2),
+        top_p: None,
+    };
+
+    // 4. Send to the model.
+    let response = client
+        .create_message(request)
+        .await
+        .map_err(|e| format!("Purge API error: {e}"))?;
+
+    crate::cost_status::report(&response.model, &response.usage);
+
+    // 5. Find the `purge_context` tool call in the response.
+    let tool_input = response.content.iter().find_map(|block| {
+        if let ContentBlock::ToolUse { name, input, .. } = block
+            && name == "purge_context"
+        {
+            return Some(input.clone());
+        }
+        None
+    });
+
+    match tool_input {
+        Some(input) => {
+            let ops = parse_purge_operations(&input, messages.len())
+                .map_err(|e| format!("Purge parse error: {e}"))?;
+            Ok(execute_purge_operations(messages, &ops))
+        }
+        None => Err("Purge: model did not call purge_context tool".to_string()),
+    }
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn msg_text(role: &str, text: &str) -> Message {
+        Message {
+            role: role.to_string(),
+            content: vec![ContentBlock::Text {
+                text: text.to_string(),
+                cache_control: None,
+            }],
+        }
+    }
+
+    fn msg_tool_use(id: &str, name: &str, input: serde_json::Value) -> Message {
+        Message {
+            role: "assistant".to_string(),
+            content: vec![ContentBlock::ToolUse {
+                id: id.to_string(),
+                name: name.to_string(),
+                input,
+                caller: None,
+            }],
+        }
+    }
+
+    fn msg_tool_result(id: &str, content: &str) -> Message {
+        Message {
+            role: "user".to_string(),
+            content: vec![ContentBlock::ToolResult {
+                tool_use_id: id.to_string(),
+                content: content.to_string(),
+                is_error: None,
+                content_blocks: None,
+            }],
+        }
+    }
+
+    #[test]
+    fn parse_remove_operations() {
+        let input = json!({
+            "operations": [
+                {"op": "remove", "msg": 1},
+                {"op": "remove", "msg": 3}
+            ]
+        });
+        let ops = parse_purge_operations(&input, 5).unwrap();
+        assert_eq!(ops.len(), 2);
+        assert!(matches!(ops[0], PurgeOp::Remove { msg_id: 1 }));
+        assert!(matches!(ops[1], PurgeOp::Remove { msg_id: 3 }));
+    }
+
+    #[test]
+    fn parse_replace_operation() {
+        let input = json!({
+            "operations": [
+                {"op": "replace", "msg": 2, "block": 0, "pattern": "hello", "with": "hi"}
+            ]
+        });
+        let ops = parse_purge_operations(&input, 5).unwrap();
+        assert_eq!(ops.len(), 1);
+        assert!(matches!(ops[0], PurgeOp::Replace { msg_id: 2, .. }));
+    }
+
+    #[test]
+    fn parse_rejects_out_of_range_msg() {
+        let input = json!({"operations": [{"op": "remove", "msg": 10}]});
+        assert!(parse_purge_operations(&input, 5).is_err());
+    }
+
+    #[test]
+    fn parse_rejects_invalid_regex() {
+        let input = json!({
+            "operations": [{"op": "replace", "msg": 1, "block": 0, "pattern": "[", "with": "x"}]
+        });
+        assert!(parse_purge_operations(&input, 5).is_err());
+    }
+
+    #[test]
+    fn execute_remove_works() {
+        let msgs = vec![
+            msg_text("user", "hello"),
+            msg_text("assistant", "hi there"),
+            msg_text("user", "bye"),
+        ];
+        let ops = vec![PurgeOp::Remove { msg_id: 2 }];
+        let result = execute_purge_operations(&msgs, &ops);
+        assert_eq!(result.removed_count, 1);
+        assert_eq!(result.messages.len(), 2);
+    }
+
+    #[test]
+    fn execute_replace_text_block() {
+        let msgs = vec![msg_text("assistant", "Hello world! Hello again!")];
+        let pattern = Regex::new("Hello").unwrap();
+        let ops = vec![PurgeOp::Replace {
+            msg_id: 1,
+            block_idx: 0,
+            pattern,
+            with: "Hi".to_string(),
+        }];
+        let result = execute_purge_operations(&msgs, &ops);
+        assert_eq!(result.replaced_count, 1);
+
+        if let ContentBlock::Text { text, .. } = &result.messages[0].content[0] {
+            assert_eq!(text, "Hi world! Hi again!");
+        } else {
+            panic!("expected text block");
+        }
+    }
+
+    #[test]
+    fn tool_call_result_pairing_cascaded() {
+        // Message 2 (idx 1) is a tool call. Message 3 (idx 2) is its result.
+        // Removing the tool call should cascade to remove the result too.
+        let msgs = vec![
+            msg_text("user", "read a file"),
+            msg_tool_use("call_01", "read_file", json!({"path": "x.rs"})),
+            msg_tool_result("call_01", "fn main() {}"),
+        ];
+        let ops = vec![PurgeOp::Remove { msg_id: 2 }]; // remove tool call only
+        let result = execute_purge_operations(&msgs, &ops);
+        // Both tool call and its result should be gone (cascaded).
+        assert_eq!(
+            result.removed_count, 2,
+            "tool call + its result should both be removed"
+        );
+        assert_eq!(result.messages.len(), 1);
+    }
+
+    #[test]
+    fn tool_result_removal_cascades_to_call() {
+        // Removing the result should cascade to remove the call.
+        let msgs = vec![
+            msg_text("user", "read a file"),
+            msg_tool_use("call_01", "read_file", json!({"path": "x.rs"})),
+            msg_tool_result("call_01", "fn main() {}"),
+        ];
+        let ops = vec![PurgeOp::Remove { msg_id: 3 }]; // remove result only
+        let result = execute_purge_operations(&msgs, &ops);
+        assert_eq!(
+            result.removed_count, 2,
+            "tool result + its call should both be removed"
+        );
+        assert_eq!(result.messages.len(), 1);
+    }
+
+    #[test]
+    fn prompt_truncates_long_content() {
+        let long_text = "x".repeat(200);
+        let msgs = vec![msg_text("user", &long_text)];
+        let prompt = build_purge_prompt(&msgs);
+        assert!(prompt.contains("(200 chars)"));
+        assert!(prompt.contains("xxx...")); // truncated
+        assert!(!prompt.contains(&long_text));
+    }
+
+    #[test]
+    fn prompt_shows_full_short_content() {
+        let msgs = vec![msg_text("user", "hi")];
+        let prompt = build_purge_prompt(&msgs);
+        assert!(prompt.contains("\"hi\""));
+        assert!(!prompt.contains("..."));
+    }
+
+    #[test]
+    fn prompt_omits_thinking_blocks() {
+        let msgs = vec![Message {
+            role: "assistant".to_string(),
+            content: vec![
+                ContentBlock::Thinking {
+                    thinking: "let me think...".to_string(),
+                },
+                ContentBlock::Text {
+                    text: "done".to_string(),
+                    cache_control: None,
+                },
+            ],
+        }];
+        let prompt = build_purge_prompt(&msgs);
+        assert!(!prompt.contains("let me think"));
+        assert!(prompt.contains("Text (4 chars)"));
+    }
+
+    #[test]
+    fn build_purge_tool_has_correct_shape() {
+        let tool = build_purge_tool();
+        assert_eq!(tool.name, "purge_context");
+        let schema = &tool.input_schema;
+        assert_eq!(schema["type"], "object");
+        assert!(schema["properties"]["operations"]["type"] == "array");
+        let ops_item = &schema["properties"]["operations"]["items"];
+        assert_eq!(ops_item["type"], "object");
+        let required = ops_item["required"].as_array().unwrap();
+        assert!(required.contains(&json!("op")));
+        assert!(required.contains(&json!("msg")));
+    }
+
+    use crate::llm_client::mock::MockLlmClient;
+    use crate::models::{MessageResponse, Usage};
+
+    fn msg_response_with_tool_call(operations: serde_json::Value) -> MessageResponse {
+        MessageResponse {
+            id: "resp_test".to_string(),
+            r#type: "message".to_string(),
+            role: "assistant".to_string(),
+            content: vec![ContentBlock::ToolUse {
+                id: "call_purge".to_string(),
+                name: "purge_context".to_string(),
+                input: json!({"operations": operations}),
+                caller: None,
+            }],
+            model: "mock-model".to_string(),
+            stop_reason: None,
+            stop_sequence: None,
+            container: None,
+            usage: Usage::default(),
+        }
+    }
+
+    fn msg_response_without_tool_call(text: &str) -> MessageResponse {
+        MessageResponse {
+            id: "resp_plain".to_string(),
+            r#type: "message".to_string(),
+            role: "assistant".to_string(),
+            content: vec![ContentBlock::Text {
+                text: text.to_string(),
+                cache_control: None,
+            }],
+            model: "mock".to_string(),
+            stop_reason: None,
+            stop_sequence: None,
+            container: None,
+            usage: Usage::default(),
+        }
+    }
+
+    #[tokio::test]
+    async fn run_purge_removes_message() {
+        let mock = MockLlmClient::new(vec![]);
+        mock.push_message_response(msg_response_with_tool_call(json!([
+            {"op": "remove", "msg": 2}
+        ])));
+
+        let messages = vec![
+            msg_text("user", "hello"),
+            msg_text("assistant", "remove me"),
+            msg_text("user", "bye"),
+        ];
+
+        let result = run_purge(&mock, &messages, "mock", None, 4096)
+            .await
+            .unwrap();
+        assert_eq!(result.removed_count, 1);
+        assert_eq!(result.replaced_count, 0);
+        assert_eq!(result.messages.len(), 2);
+
+        if let ContentBlock::Text { text, .. } = &result.messages[0].content[0] {
+            assert_eq!(text, "hello");
+        } else {
+            panic!(
+                "expected text block, got {:?}",
+                &result.messages[0].content[0]
+            );
+        }
+        if let ContentBlock::Text { text, .. } = &result.messages[1].content[0] {
+            assert_eq!(text, "bye");
+        } else {
+            panic!(
+                "expected text block, got {:?}",
+                &result.messages[1].content[0]
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn run_purge_replace_condenses_text() {
+        let mock = MockLlmClient::new(vec![]);
+        mock.push_message_response(msg_response_with_tool_call(json!([
+            {"op": "replace", "msg": 1, "block": 0, "pattern": "very long and verbose", "with": "short"}
+        ])));
+
+        let messages = vec![msg_text("assistant", "this is very long and verbose text")];
+
+        let result = run_purge(&mock, &messages, "mock", None, 4096)
+            .await
+            .unwrap();
+        assert_eq!(result.removed_count, 0);
+        assert_eq!(result.replaced_count, 1);
+
+        if let ContentBlock::Text { text, .. } = &result.messages[0].content[0] {
+            assert_eq!(text, "this is short text");
+        } else {
+            panic!(
+                "expected text block, got {:?}",
+                &result.messages[0].content[0]
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn run_purge_errors_when_no_tool_call() {
+        let mock = MockLlmClient::new(vec![]);
+        mock.push_message_response(msg_response_without_tool_call("nothing to clean up"));
+
+        let messages = vec![msg_text("user", "hi")];
+        let err = run_purge(&mock, &messages, "mock", None, 4096)
+            .await
+            .unwrap_err();
+        assert!(err.contains("did not call purge_context"));
+    }
+
+    #[tokio::test]
+    async fn run_purge_errors_on_api_failure() {
+        // No canned response — MockLlmClient returns an error.
+        let mock = MockLlmClient::new(vec![]);
+        let messages = vec![msg_text("user", "hi")];
+        let err = run_purge(&mock, &messages, "mock", None, 4096)
+            .await
+            .unwrap_err();
+        assert!(err.contains("Purge API error"));
+    }
+}
diff --git a/crates/tui/src/runtime_api.rs b/crates/tui/src/runtime_api.rs
index 20110cc4..63bb718e 100644
--- a/crates/tui/src/runtime_api.rs
+++ b/crates/tui/src/runtime_api.rs
@@ -3,8 +3,8 @@
 use std::collections::HashSet;
 use std::convert::Infallible;
 use std::fs;
-use std::net::SocketAddr;
-use std::path::PathBuf;
+use std::net::{SocketAddr, UdpSocket};
+use std::path::{Path as FsPath, PathBuf};
 use std::process::Command;
 use std::sync::Arc;
 use std::time::Duration;
@@ -14,6 +14,7 @@ use async_stream::stream;
 use axum::extract::{Path, Query, Request, State};
 use axum::http::{HeaderValue, Method, StatusCode, header};
 use axum::middleware::{self, Next};
+use axum::response::Html;
 use axum::response::sse::{Event as SseEvent, KeepAlive, Sse};
 use axum::response::{IntoResponse, Response};
 use axum::routing::{get, post};
@@ -40,7 +41,6 @@ use crate::runtime_threads::{
 };
 use crate::session_manager::{SavedSession, SessionManager, SessionMetadata, default_sessions_dir};
 use crate::skill_state::SkillStateStore;
-use crate::skills::SkillRegistry;
 use crate::task_manager::{
     NewTaskRequest, SharedTaskManager, TaskManager, TaskManagerConfig, TaskRecord, TaskSummary,
 };
@@ -60,6 +60,7 @@ pub struct RuntimeApiState {
     auth_required: bool,
     bind_host: String,
     bind_port: u16,
+    mobile_enabled: bool,
 }
 
 #[derive(Debug, Clone)]
@@ -78,6 +79,8 @@ pub struct RuntimeApiOptions {
     pub auth_token: Option<String>,
     /// Allow `/v1/*` routes without auth when no token is configured.
     pub insecure_no_auth: bool,
+    /// Enables the built-in mobile control page at `/mobile`.
+    pub mobile: bool,
 }
 
 impl Default for RuntimeApiOptions {
@@ -89,6 +92,7 @@ impl Default for RuntimeApiOptions {
             cors_origins: Vec::new(),
             auth_token: None,
             insecure_no_auth: false,
+            mobile: false,
         }
     }
 }
@@ -261,11 +265,13 @@ struct SkillEntry {
     description: String,
     path: PathBuf,
     enabled: bool,
+    is_bundled: bool,
 }
 
 #[derive(Debug, Serialize)]
 struct SkillsResponse {
     directory: PathBuf,
+    directories: Vec<PathBuf>,
     warnings: Vec<String>,
     skills: Vec<SkillEntry>,
 }
@@ -296,6 +302,25 @@ struct DecideApprovalResponse {
     delivered: bool,
 }
 
+#[derive(Debug, Deserialize)]
+struct SubmitUserInputBody {
+    answers: Vec<UserInputAnswerBody>,
+}
+
+#[derive(Debug, Deserialize)]
+struct UserInputAnswerBody {
+    id: String,
+    label: String,
+    value: String,
+}
+
+#[derive(Debug, Serialize)]
+struct SubmitUserInputResponse {
+    ok: bool,
+    input_id: String,
+    delivered: bool,
+}
+
 #[derive(Debug, Serialize)]
 struct RuntimeInfoResponse {
     bind_host: String,
@@ -423,6 +448,7 @@ pub async fn run_http_server(
         auth_required: auth_enabled,
         bind_host: options.host.clone(),
         bind_port: options.port,
+        mobile_enabled: options.mobile,
     };
     let app = build_router(state);
 
@@ -445,6 +471,9 @@ pub async fn run_http_server(
     } else {
         println!("Runtime API auth: disabled by explicit insecure mode.");
     }
+    if options.mobile {
+        print_mobile_urls(addr, runtime_token.as_deref(), auth_enabled);
+    }
     let is_loopback = options.host == "127.0.0.1" || options.host == "::1";
     if is_loopback {
         println!("Security: this server is local-first. Do not expose it to untrusted networks.");
@@ -500,6 +529,10 @@ pub fn build_router(state: RuntimeApiState) -> Router {
         .route("/v1/threads/{id}/compact", post(compact_thread))
         .route("/v1/threads/{id}/events", get(stream_thread_events))
         .route("/v1/approvals/{approval_id}", post(decide_approval))
+        .route(
+            "/v1/user-input/{thread_id}/{input_id}",
+            post(submit_user_input),
+        )
         .route("/v1/tasks", get(list_tasks).post(create_task))
         .route("/v1/tasks/{id}", get(get_task))
         .route("/v1/tasks/{id}/cancel", post(cancel_task))
@@ -529,6 +562,8 @@ pub fn build_router(state: RuntimeApiState) -> Router {
 
     Router::new()
         .route("/health", get(health))
+        .route("/mobile", get(mobile_page))
+        .route("/mobile/", get(mobile_page))
         .route("/v1/runtime/info", get(runtime_info))
         .merge(api_routes)
         .layer(cors_layer(&state.cors_origins))
@@ -543,8 +578,17 @@ async fn require_runtime_token(
     let Some(expected) = state.runtime_token.as_deref() else {
         return next.run(req).await;
     };
-    let authorized = req
-        .headers()
+    let authorized = request_has_runtime_token(&req, expected);
+
+    if authorized {
+        next.run(req).await
+    } else {
+        runtime_token_required_response()
+    }
+}
+
+fn request_has_runtime_token(req: &Request, expected: &str) -> bool {
+    req.headers()
         .get(header::AUTHORIZATION)
         .and_then(|value| value.to_str().ok())
         .and_then(|raw| raw.strip_prefix("Bearer "))
@@ -554,33 +598,127 @@ async fn require_runtime_token(
             .get("x-deepseek-runtime-token")
             .and_then(|value| value.to_str().ok())
             .is_some_and(|token| token == expected)
-        || token_from_query(req.uri().query()).is_some_and(|token| token == expected);
-
-    if authorized {
-        next.run(req).await
-    } else {
-        (
-            StatusCode::UNAUTHORIZED,
-            Json(json!({
-                "error": {
-                    "message": "runtime API bearer token required",
-                    "status": StatusCode::UNAUTHORIZED.as_u16(),
-                }
-            })),
-        )
-            .into_response()
-    }
+        || token_from_query(req.uri().query()).is_some_and(|token| token == expected)
 }
 
-fn token_from_query(query: Option<&str>) -> Option<&str> {
+fn runtime_token_required_response() -> Response {
+    (
+        StatusCode::UNAUTHORIZED,
+        Json(json!({
+            "error": {
+                "message": "runtime API bearer token required",
+                "status": StatusCode::UNAUTHORIZED.as_u16(),
+            }
+        })),
+    )
+        .into_response()
+}
+
+fn token_from_query(query: Option<&str>) -> Option<String> {
     query.and_then(|query| {
         query.split('&').find_map(|pair| {
             let (key, value) = pair.split_once('=')?;
-            (key == "token").then_some(value)
+            (key == "token")
+                .then(|| percent_decode_query_component(value))
+                .flatten()
         })
     })
 }
 
+fn percent_decode_query_component(value: &str) -> Option<String> {
+    let bytes = value.as_bytes();
+    let mut decoded = Vec::with_capacity(bytes.len());
+    let mut index = 0;
+    while index < bytes.len() {
+        match bytes[index] {
+            b'%' => {
+                let hi = *bytes.get(index + 1)?;
+                let lo = *bytes.get(index + 2)?;
+                let hi = (hi as char).to_digit(16)? as u8;
+                let lo = (lo as char).to_digit(16)? as u8;
+                decoded.push((hi << 4) | lo);
+                index += 3;
+            }
+            b'+' => {
+                decoded.push(b' ');
+                index += 1;
+            }
+            byte => {
+                decoded.push(byte);
+                index += 1;
+            }
+        }
+    }
+    String::from_utf8(decoded).ok()
+}
+
+async fn mobile_page(State(state): State<RuntimeApiState>, req: Request) -> Response {
+    if !state.mobile_enabled {
+        return (
+            StatusCode::NOT_FOUND,
+            "mobile control is disabled; start with `codewhale serve --mobile`",
+        )
+            .into_response();
+    }
+    if let Some(expected) = state.runtime_token.as_deref()
+        && !request_has_runtime_token(&req, expected)
+    {
+        return runtime_token_required_response();
+    }
+    Html(MOBILE_HTML).into_response()
+}
+
+fn print_mobile_urls(addr: SocketAddr, token: Option<&str>, auth_enabled: bool) {
+    println!("Mobile control page enabled.");
+    let token_query = if auth_enabled {
+        token
+            .filter(|token| !token.trim().is_empty())
+            .map(|token| format!("?token={}", url_query_component(token)))
+            .unwrap_or_default()
+    } else {
+        String::new()
+    };
+
+    let port = addr.port();
+    if addr.ip().is_unspecified() {
+        println!("  Local: http://127.0.0.1:{port}/mobile{token_query}");
+        if let Some(ip) = detect_lan_ip() {
+            println!("  LAN:   http://{ip}:{port}/mobile{token_query}");
+        } else {
+            println!(
+                "  LAN:   bind is 0.0.0.0; open http://<this-machine-ip>:{port}/mobile{token_query}"
+            );
+        }
+    } else {
+        println!("  URL:   http://{addr}/mobile{token_query}");
+    }
+    println!("Mobile security: use only on a trusted LAN/VPN; this server does not provide TLS.");
+}
+
+fn url_query_component(value: &str) -> String {
+    let mut encoded = String::with_capacity(value.len());
+    for byte in value.bytes() {
+        match byte {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
+                encoded.push(byte as char);
+            }
+            _ => {
+                use std::fmt::Write as _;
+                let _ = write!(encoded, "%{byte:02X}");
+            }
+        }
+    }
+    encoded
+}
+
+fn detect_lan_ip() -> Option<String> {
+    let socket = UdpSocket::bind("0.0.0.0:0").ok()?;
+    // UDP connect only selects the outbound interface locally; no packet is sent.
+    socket.connect("10.255.255.255:1").ok()?;
+    let addr = socket.local_addr().ok()?;
+    Some(addr.ip().to_string())
+}
+
 async fn health() -> Json<HealthResponse> {
     Json(HealthResponse {
         status: "ok",
@@ -707,7 +845,38 @@ fn session_to_detail(session: SavedSession) -> SessionDetailResponse {
                     crate::models::ContentBlock::Thinking { thinking, .. } => {
                         json!({ "type": "thinking", "text": thinking })
                     }
-                    _ => json!({ "type": "other" }),
+                    crate::models::ContentBlock::ToolUse { id, name, input, caller } => {
+                        let mut obj =
+                            json!({ "type": "tool_use", "id": id, "name": name, "input": input });
+                        if let Some(caller) = caller {
+                            obj["caller"] = json!(caller);
+                        }
+                        obj
+                    }
+                    crate::models::ContentBlock::ToolResult { tool_use_id, content, is_error, content_blocks, .. } => {
+                        let mut obj = json!({ "type": "tool_result", "tool_use_id": tool_use_id });
+                        if let Some(cbs) = content_blocks {
+                            obj["content_blocks"] = json!(cbs);
+                            if !content.is_empty() {
+                                obj["content"] = json!(content);
+                            }
+                        } else {
+                            obj["content"] = json!(content);
+                        }
+                        if let Some(e) = is_error {
+                            obj["is_error"] = json!(e);
+                        }
+                        obj
+                    }
+                    crate::models::ContentBlock::ServerToolUse { id, name, input } => {
+                        json!({ "type": "tool_use", "id": id, "name": name, "input": input })
+                    }
+                    crate::models::ContentBlock::ToolSearchToolResult { tool_use_id, content } => {
+                        json!({ "type": "tool_result", "tool_use_id": tool_use_id, "content": content })
+                    }
+                    crate::models::ContentBlock::CodeExecutionToolResult { tool_use_id, content } => {
+                        json!({ "type": "tool_result", "tool_use_id": tool_use_id, "content": content })
+                    }
                 })
                 .collect();
             json!({
@@ -906,7 +1075,7 @@ async fn list_skills(
     State(state): State<RuntimeApiState>,
 ) -> Result<Json<SkillsResponse>, ApiError> {
     let skills_dir = resolve_skills_dir(&state.config, &state.workspace);
-    let registry = SkillRegistry::discover(&skills_dir);
+    let (registry, directories) = discover_skills_for_runtime_api(&state.workspace, &skills_dir);
     let skill_state = state.skill_state.lock().await;
     let skills = registry
         .list()
@@ -914,12 +1083,14 @@ async fn list_skills(
         .map(|skill| SkillEntry {
             name: skill.name.clone(),
             description: skill.description.clone(),
-            path: skills_dir.join(&skill.name).join("SKILL.md"),
+            path: skill.path.clone(),
             enabled: skill_state.is_enabled(&skill.name),
+            is_bundled: skill_entry_is_bundled(skill, &skills_dir),
         })
         .collect();
     Ok(Json(SkillsResponse {
         directory: skills_dir,
+        directories,
         warnings: registry.warnings().to_vec(),
         skills,
     }))
@@ -931,12 +1102,12 @@ async fn set_skill_enabled(
     Json(req): Json<SetSkillEnabledRequest>,
 ) -> Result<Json<SetSkillEnabledResponse>, ApiError> {
     let skills_dir = resolve_skills_dir(&state.config, &state.workspace);
-    let registry = SkillRegistry::discover(&skills_dir);
+    let (registry, directories) = discover_skills_for_runtime_api(&state.workspace, &skills_dir);
     let exists = registry.list().iter().any(|skill| skill.name == name);
     if !exists {
         return Err(ApiError::not_found(format!(
-            "skill '{name}' not found under {}",
-            skills_dir.display()
+            "skill '{name}' not found in searched directories: {}",
+            format_skill_search_paths(&directories)
         )));
     }
 
@@ -984,6 +1155,34 @@ async fn decide_approval(
     }))
 }
 
+async fn submit_user_input(
+    State(state): State<RuntimeApiState>,
+    Path((thread_id, input_id)): Path<(String, String)>,
+    Json(req): Json<SubmitUserInputBody>,
+) -> Result<Json<SubmitUserInputResponse>, ApiError> {
+    use crate::tools::user_input::{UserInputAnswer, UserInputResponse};
+    let answers: Vec<UserInputAnswer> = req
+        .answers
+        .into_iter()
+        .map(|a| UserInputAnswer {
+            id: a.id,
+            label: a.label,
+            value: a.value,
+        })
+        .collect();
+    let response = UserInputResponse { answers };
+    let delivered = state
+        .runtime_threads
+        .submit_user_input(&thread_id, &input_id, response)
+        .await
+        .map_err(map_thread_err)?;
+    Ok(Json(SubmitUserInputResponse {
+        ok: true,
+        input_id,
+        delivered,
+    }))
+}
+
 async fn runtime_info(State(state): State<RuntimeApiState>) -> Json<RuntimeInfoResponse> {
     Json(RuntimeInfoResponse {
         bind_host: state.bind_host.clone(),
@@ -1562,6 +1761,8 @@ fn map_compat_stream_event(event: &crate::runtime_threads::RuntimeEventRecord) -
             }
         }
         "approval.required" => Some(sse_json("approval.required", payload.clone())),
+        "approval.decided" => Some(sse_json("approval.decided", payload.clone())),
+        "approval.timeout" => Some(sse_json("approval.timeout", payload.clone())),
         "sandbox.denied" => Some(sse_json("sandbox.denied", payload.clone())),
         "turn.completed" => {
             let usage = payload
@@ -1684,6 +1885,50 @@ fn resolve_skills_dir(config: &Config, workspace: &std::path::Path) -> PathBuf {
     config.skills_dir()
 }
 
+fn skills_search_directories(workspace: &FsPath, skills_dir: &FsPath) -> Vec<PathBuf> {
+    let mut directories = crate::skills::skills_directories(workspace);
+    if skills_dir.is_dir() && !directories.iter().any(|path| path == skills_dir) {
+        directories.push(skills_dir.to_path_buf());
+    }
+    directories
+}
+
+fn discover_skills_for_runtime_api(
+    workspace: &FsPath,
+    skills_dir: &FsPath,
+) -> (crate::skills::SkillRegistry, Vec<PathBuf>) {
+    let directories = skills_search_directories(workspace, skills_dir);
+    let registry = crate::skills::discover_from_directories(directories.clone());
+    (registry, directories)
+}
+
+fn skill_entry_is_bundled(skill: &crate::skills::Skill, skills_dir: &FsPath) -> bool {
+    if !crate::skills::is_bundled_skill_name(&skill.name) {
+        return false;
+    }
+
+    let expected_path = skills_dir.join(&skill.name).join("SKILL.md");
+    paths_refer_to_same_file(&skill.path, &expected_path)
+}
+
+fn paths_refer_to_same_file(left: &FsPath, right: &FsPath) -> bool {
+    match (fs::canonicalize(left), fs::canonicalize(right)) {
+        (Ok(left), Ok(right)) => left == right,
+        _ => left == right,
+    }
+}
+
+fn format_skill_search_paths(directories: &[PathBuf]) -> String {
+    if directories.is_empty() {
+        return "<none>".to_string();
+    }
+    directories
+        .iter()
+        .map(|path| path.display().to_string())
+        .collect::<Vec<_>>()
+        .join(", ")
+}
+
 fn load_mcp_config_or_default(path: &std::path::Path) -> Result<McpConfig, ApiError> {
     crate::mcp::load_config(path)
         .map_err(|e| ApiError::internal(format!("Failed to load MCP config: {e:#}")))
@@ -1742,6 +1987,8 @@ async fn get_usage(
     Ok(Json(json!(aggregation)))
 }
 
+const MOBILE_HTML: &str = include_str!("runtime_mobile.html");
+
 /// Built-in dev origins always allowed by the runtime API (whalescale#255).
 const DEFAULT_CORS_ORIGINS: &[&str] = &[
     "http://localhost:3000",
@@ -1906,6 +2153,78 @@ mod tests {
         }
     }
 
+    fn saved_session_with_blocks(blocks: Vec<crate::models::ContentBlock>) -> SavedSession {
+        SavedSession {
+            schema_version: 1,
+            metadata: SessionMetadata {
+                id: "session-1".to_string(),
+                title: "test session".to_string(),
+                created_at: Utc::now(),
+                updated_at: Utc::now(),
+                message_count: 1,
+                total_tokens: 0,
+                model: "test-model".to_string(),
+                workspace: PathBuf::from("."),
+                mode: None,
+                cost: Default::default(),
+                parent_session_id: None,
+                forked_from_message_count: None,
+                cumulative_turn_secs: 0,
+            },
+            messages: vec![crate::models::Message {
+                role: "assistant".to_string(),
+                content: blocks,
+            }],
+            system_prompt: None,
+            context_references: Vec::new(),
+            artifacts: Vec::new(),
+        }
+    }
+
+    #[test]
+    fn session_detail_tool_use_preserves_caller_metadata() {
+        let detail = session_to_detail(saved_session_with_blocks(vec![
+            crate::models::ContentBlock::ToolUse {
+                id: "tool-1".to_string(),
+                name: "task_shell_start".to_string(),
+                input: json!({ "cmd": "cargo test" }),
+                caller: Some(crate::models::ToolCaller {
+                    caller_type: "subagent".to_string(),
+                    tool_id: Some("parent-tool".to_string()),
+                }),
+            },
+        ]));
+
+        let block = &detail.messages[0]["content"][0];
+        assert_eq!(block["type"].as_str(), Some("tool_use"));
+        assert_eq!(block["caller"]["type"].as_str(), Some("subagent"));
+        assert_eq!(block["caller"]["tool_id"].as_str(), Some("parent-tool"));
+    }
+
+    #[test]
+    fn session_detail_tool_result_keeps_fallback_content_with_blocks() {
+        let detail = session_to_detail(saved_session_with_blocks(vec![
+            crate::models::ContentBlock::ToolResult {
+                tool_use_id: "tool-1".to_string(),
+                content: "fallback text".to_string(),
+                is_error: Some(false),
+                content_blocks: Some(vec![json!({
+                    "type": "text",
+                    "text": "structured text"
+                })]),
+            },
+        ]));
+
+        let block = &detail.messages[0]["content"][0];
+        assert_eq!(block["type"].as_str(), Some("tool_result"));
+        assert_eq!(block["content"].as_str(), Some("fallback text"));
+        assert_eq!(
+            block["content_blocks"][0]["text"].as_str(),
+            Some("structured text")
+        );
+        assert_eq!(block["is_error"].as_bool(), Some(false));
+    }
+
     #[test]
     fn runtime_auth_generates_token_by_default() {
         let auth = resolve_runtime_auth(None, None, false);
@@ -1950,6 +2269,23 @@ mod tests {
         assert!(auth.token.is_some());
     }
 
+    #[test]
+    fn url_query_component_percent_encodes_token() {
+        assert_eq!(
+            url_query_component("abc ABC+/?:=&%"),
+            "abc%20ABC%2B%2F%3F%3A%3D%26%25"
+        );
+    }
+
+    #[test]
+    fn token_from_query_decodes_percent_encoded_token() {
+        assert_eq!(
+            token_from_query(Some("since_seq=0&token=abc%20ABC%2B%2F%3F%3A%3D%26%25")),
+            Some("abc ABC+/?:=&%".to_string())
+        );
+        assert_eq!(token_from_query(Some("token=bad%ZZ")), None);
+    }
+
     async fn spawn_test_server_with_root(
         root: PathBuf,
         sessions_dir: PathBuf,
@@ -1973,6 +2309,21 @@ mod tests {
             SharedRuntimeThreadManager,
             tokio::task::JoinHandle<()>,
         )>,
+    > {
+        spawn_test_server_with_root_token_and_mobile(root, sessions_dir, runtime_token, false).await
+    }
+
+    async fn spawn_test_server_with_root_token_and_mobile(
+        root: PathBuf,
+        sessions_dir: PathBuf,
+        runtime_token: Option<String>,
+        mobile_enabled: bool,
+    ) -> Result<
+        Option<(
+            SocketAddr,
+            SharedRuntimeThreadManager,
+            tokio::task::JoinHandle<()>,
+        )>,
     > {
         fs::create_dir_all(&sessions_dir)?;
         let manager = TaskManager::start_with_executor(
@@ -2035,6 +2386,7 @@ mod tests {
             auth_required,
             bind_host: "127.0.0.1".to_string(),
             bind_port: 0,
+            mobile_enabled,
         };
         let app = build_router(state);
         let listener = match TcpListener::bind("127.0.0.1:0").await {
@@ -3600,6 +3952,115 @@ mod tests {
         Ok(())
     }
 
+    #[tokio::test]
+    async fn mobile_page_is_available_only_when_enabled() -> Result<()> {
+        let tmp = tempfile::tempdir()?;
+        let root = tmp.path().to_path_buf();
+        let sessions_dir = root.join("sessions");
+        let Some((addr, _runtime_threads, handle)) = spawn_test_server_with_root_token_and_mobile(
+            root.clone(),
+            sessions_dir.clone(),
+            None,
+            false,
+        )
+        .await?
+        else {
+            return Ok(());
+        };
+        let client = reqwest::Client::new();
+        let disabled = client.get(format!("http://{addr}/mobile")).send().await?;
+        assert_eq!(disabled.status(), StatusCode::NOT_FOUND);
+        handle.abort();
+
+        let Some((addr, _runtime_threads, handle)) =
+            spawn_test_server_with_root_token_and_mobile(root, sessions_dir, None, true).await?
+        else {
+            return Ok(());
+        };
+        let enabled = client
+            .get(format!("http://{addr}/mobile"))
+            .send()
+            .await?
+            .error_for_status()?;
+        let html = enabled.text().await?;
+        assert!(html.contains("CodeWhale Mobile"));
+        assert!(html.contains("/v1/approvals/"));
+
+        handle.abort();
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn mobile_page_requires_runtime_token_when_auth_enabled() -> Result<()> {
+        let tmp = tempfile::tempdir()?;
+        let root = tmp.path().to_path_buf();
+        let sessions_dir = root.join("sessions");
+        let token = "abc ABC+/?:=&%".to_string();
+        let Some((addr, _runtime_threads, handle)) = spawn_test_server_with_root_token_and_mobile(
+            root,
+            sessions_dir,
+            Some(token.clone()),
+            true,
+        )
+        .await?
+        else {
+            return Ok(());
+        };
+        let client = reqwest::Client::new();
+
+        let unauthorized = client.get(format!("http://{addr}/mobile")).send().await?;
+        assert_eq!(unauthorized.status(), StatusCode::UNAUTHORIZED);
+
+        let encoded = url_query_component(&token);
+        let query = client
+            .get(format!("http://{addr}/mobile?token={encoded}"))
+            .send()
+            .await?
+            .error_for_status()?;
+        assert!(query.text().await?.contains("CodeWhale Mobile"));
+
+        let bearer = client
+            .get(format!("http://{addr}/mobile"))
+            .bearer_auth(&token)
+            .send()
+            .await?
+            .error_for_status()?;
+        assert!(bearer.text().await?.contains("CodeWhale Mobile"));
+
+        handle.abort();
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn mobile_insecure_mode_allows_page_and_v1_routes_without_token() -> Result<()> {
+        let tmp = tempfile::tempdir()?;
+        let root = tmp.path().to_path_buf();
+        let sessions_dir = root.join("sessions");
+        let Some((addr, _runtime_threads, handle)) =
+            spawn_test_server_with_root_token_and_mobile(root, sessions_dir, None, true).await?
+        else {
+            return Ok(());
+        };
+        let client = reqwest::Client::new();
+
+        let page = client
+            .get(format!("http://{addr}/mobile"))
+            .send()
+            .await?
+            .error_for_status()?;
+        assert!(page.text().await?.contains("CodeWhale Mobile"));
+
+        let summary = client
+            .get(format!("http://{addr}/v1/threads/summary"))
+            .send()
+            .await?
+            .error_for_status()?;
+        assert_eq!(summary.status(), StatusCode::OK);
+
+        handle.abort();
+        Ok(())
+    }
+
     #[tokio::test]
     async fn decide_approval_404s_when_nothing_pending() -> Result<()> {
         let Some((addr, _runtime_threads, handle)) = spawn_test_server().await? else {
@@ -3731,6 +4192,71 @@ mod tests {
         assert_eq!(resolved, expected);
     }
 
+    #[test]
+    fn skills_search_directories_includes_custom_skills_dir() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let workspace = tmp.path().join("workspace");
+        let custom_skills = tmp.path().join("custom-skills");
+        fs::create_dir_all(&workspace).expect("create workspace");
+        fs::create_dir_all(&custom_skills).expect("create custom skills");
+
+        let directories = skills_search_directories(&workspace, &custom_skills);
+
+        assert!(
+            directories.iter().any(|dir| dir == &custom_skills),
+            "custom skills_dir must be reported when discovery searches it"
+        );
+        let message = format_skill_search_paths(&directories);
+        assert!(message.contains("custom-skills"));
+    }
+
+    #[test]
+    fn skill_entry_is_bundled_requires_configured_bundle_path() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let bundled_skills_dir = tmp.path().join("bundled-skills");
+        let bundled_skill_path = bundled_skills_dir.join("delegate").join("SKILL.md");
+        let override_skill_path = tmp
+            .path()
+            .join("workspace")
+            .join(".agents")
+            .join("skills")
+            .join("delegate")
+            .join("SKILL.md");
+        fs::create_dir_all(bundled_skill_path.parent().expect("bundled parent"))
+            .expect("create bundled skill dir");
+        fs::create_dir_all(override_skill_path.parent().expect("override parent"))
+            .expect("create override skill dir");
+        fs::write(
+            &bundled_skill_path,
+            "---\nname: delegate\ndescription: bundled\n---\n",
+        )
+        .expect("write bundled skill");
+        fs::write(
+            &override_skill_path,
+            "---\nname: delegate\ndescription: override\n---\n",
+        )
+        .expect("write override skill");
+
+        let bundled_skill = crate::skills::Skill {
+            name: "delegate".to_string(),
+            description: String::new(),
+            body: String::new(),
+            path: bundled_skill_path,
+        };
+        let override_skill = crate::skills::Skill {
+            name: "delegate".to_string(),
+            description: String::new(),
+            body: String::new(),
+            path: override_skill_path,
+        };
+
+        assert!(skill_entry_is_bundled(&bundled_skill, &bundled_skills_dir));
+        assert!(!skill_entry_is_bundled(
+            &override_skill,
+            &bundled_skills_dir
+        ));
+    }
+
     /// A `skills` symlink that points outside the workspace must NOT be
     /// returned as the resolved skills directory. Containment check ensures
     /// the canonicalized candidate stays under the canonicalized workspace
diff --git a/crates/tui/src/runtime_log.rs b/crates/tui/src/runtime_log.rs
index 7fa0e8ca..fd631f66 100644
--- a/crates/tui/src/runtime_log.rs
+++ b/crates/tui/src/runtime_log.rs
@@ -1,5 +1,5 @@
 //! TUI runtime logging. Initializes a `tracing-subscriber` that writes to a
-//! per-process file under `~/.deepseek/logs/tui-YYYY-MM-DD-PID.log`, and (on
+//! per-process file under `~/.codewhale/logs/tui-YYYY-MM-DD-PID.log`, and (on
 //! Unix) redirects the process's `stderr` fd to that same file for the lifetime
 //! of the alt-screen TUI.
 //!
@@ -22,7 +22,7 @@
 //!
 //! Defence-in-depth:
 //!   1. A `tracing-subscriber` writes formatted logs to
-//!      `~/.deepseek/logs/tui-YYYY-MM-DD-PID.log` so `tracing::warn!` /
+//!      `~/.codewhale/logs/tui-YYYY-MM-DD-PID.log` so `tracing::warn!` /
 //!      `tracing::error!` calls go somewhere observable instead of
 //!      disappearing into the void (the TUI previously had no global
 //!      subscriber, so contributors reached for `eprintln!`).
@@ -156,18 +156,29 @@ pub fn init() -> Result<TuiLogGuard> {
     })
 }
 
-fn log_directory() -> Option<PathBuf> {
+pub(crate) fn log_directory() -> Option<PathBuf> {
+    let resolve = |base: PathBuf| -> Option<PathBuf> {
+        let primary = base.join(".codewhale").join("logs");
+        if primary.exists() {
+            return Some(primary);
+        }
+        let legacy = base.join(".deepseek").join("logs");
+        if legacy.exists() {
+            return Some(legacy);
+        }
+        Some(primary)
+    };
     if let Some(home) = std::env::var_os("HOME").map(PathBuf::from)
         && !home.as_os_str().is_empty()
     {
-        return Some(home.join(".deepseek").join("logs"));
+        return resolve(home);
     }
     if let Some(userprofile) = std::env::var_os("USERPROFILE").map(PathBuf::from)
         && !userprofile.as_os_str().is_empty()
     {
-        return Some(userprofile.join(".deepseek").join("logs"));
+        return resolve(userprofile);
     }
-    dirs::home_dir().map(|h| h.join(".deepseek").join("logs"))
+    dirs::home_dir().and_then(resolve)
 }
 
 fn log_file_name(date: &str, pid: u32) -> String {
@@ -263,7 +274,37 @@ mod tests {
         }
 
         let resolved = log_directory().expect("log_directory should resolve");
-        assert_eq!(resolved, tmp.path().join(".deepseek").join("logs"));
+        assert_eq!(resolved, tmp.path().join(".codewhale").join("logs"));
+
+        // SAFETY: cleanup under the same lock.
+        unsafe {
+            match prev_home {
+                Some(v) => std::env::set_var("HOME", v),
+                None => std::env::remove_var("HOME"),
+            }
+            match prev_userprofile {
+                Some(v) => std::env::set_var("USERPROFILE", v),
+                None => std::env::remove_var("USERPROFILE"),
+            }
+        }
+    }
+
+    #[test]
+    fn log_directory_uses_existing_legacy_deepseek_logs() {
+        let _lock = crate::test_support::lock_test_env();
+        let tmp = tempfile::TempDir::new().unwrap();
+        let legacy = tmp.path().join(".deepseek").join("logs");
+        fs::create_dir_all(&legacy).unwrap();
+        let prev_home = std::env::var_os("HOME");
+        let prev_userprofile = std::env::var_os("USERPROFILE");
+        // SAFETY: serialised by lock_test_env.
+        unsafe {
+            std::env::set_var("HOME", tmp.path());
+            std::env::set_var("USERPROFILE", "");
+        }
+
+        let resolved = log_directory().expect("log_directory should resolve");
+        assert_eq!(resolved, legacy);
 
         // SAFETY: cleanup under the same lock.
         unsafe {
diff --git a/crates/tui/src/runtime_mobile.html b/crates/tui/src/runtime_mobile.html
new file mode 100644
index 00000000..be1cae50
--- /dev/null
+++ b/crates/tui/src/runtime_mobile.html
@@ -0,0 +1,549 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <title>CodeWhale Mobile</title>
+  <style>
+    :root {
+      color-scheme: dark;
+      --bg: #101214;
+      --panel: #181b1f;
+      --panel-2: #20242a;
+      --line: #323840;
+      --text: #f4f1e8;
+      --muted: #a8a49a;
+      --accent: #48c2a8;
+      --accent-2: #c89543;
+      --danger: #e86458;
+      --ok: #76c46b;
+    }
+    * { box-sizing: border-box; }
+    html, body { min-height: 100%; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font: 15px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      letter-spacing: 0;
+    }
+    header {
+      position: sticky;
+      top: 0;
+      z-index: 4;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+      padding: calc(12px + env(safe-area-inset-top)) 14px 12px;
+      background: rgba(16, 18, 20, 0.96);
+      border-bottom: 1px solid var(--line);
+      backdrop-filter: blur(12px);
+    }
+    h1 {
+      margin: 0;
+      font-size: 18px;
+      font-weight: 740;
+    }
+    main {
+      display: grid;
+      gap: 12px;
+      padding: 12px 12px calc(14px + env(safe-area-inset-bottom));
+    }
+    section {
+      border: 1px solid var(--line);
+      background: var(--panel);
+      border-radius: 8px;
+      overflow: hidden;
+    }
+    .head {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+      padding: 10px 12px;
+      border-bottom: 1px solid var(--line);
+      min-height: 46px;
+    }
+    .body { padding: 12px; }
+    .grid { display: grid; gap: 10px; }
+    .row { display: flex; align-items: center; gap: 8px; }
+    .row > * { flex: 1; min-width: 0; }
+    button, input, textarea, select {
+      color: var(--text);
+      background: var(--panel-2);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      font: inherit;
+      letter-spacing: 0;
+    }
+    button {
+      min-height: 40px;
+      padding: 8px 11px;
+      font-weight: 680;
+      cursor: pointer;
+    }
+    button.primary {
+      background: #173d36;
+      border-color: #2a8b77;
+    }
+    button.warn {
+      background: #3c2b14;
+      border-color: #8b682b;
+    }
+    button.danger {
+      background: #421f1d;
+      border-color: #9b4038;
+    }
+    button:disabled {
+      cursor: not-allowed;
+      opacity: 0.55;
+    }
+    input, textarea, select {
+      width: 100%;
+      padding: 10px;
+    }
+    textarea {
+      min-height: 96px;
+      resize: vertical;
+    }
+    label.toggle {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      min-height: 40px;
+      padding: 8px 10px;
+      color: var(--muted);
+      background: var(--panel-2);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      font-size: 13px;
+    }
+    label.toggle input { width: auto; }
+    .status {
+      min-height: 38px;
+      padding: 9px 10px;
+      border-radius: 8px;
+      background: #121518;
+      border: 1px solid var(--line);
+      color: var(--muted);
+      overflow-wrap: anywhere;
+    }
+    .status.ok { color: var(--ok); }
+    .status.bad { color: var(--danger); }
+    .status.warn { color: var(--accent-2); }
+    #threads {
+      display: grid;
+      gap: 8px;
+      max-height: 260px;
+      overflow: auto;
+    }
+    .thread {
+      width: 100%;
+      padding: 10px;
+      text-align: left;
+      border-radius: 8px;
+      background: var(--panel-2);
+    }
+    .thread.active { border-color: var(--accent); }
+    .thread-title {
+      font-weight: 720;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    .meta {
+      margin-top: 3px;
+      color: var(--muted);
+      font-size: 12px;
+      overflow-wrap: anywhere;
+    }
+    #events {
+      display: grid;
+      gap: 8px;
+      max-height: 54vh;
+      overflow: auto;
+      padding-right: 2px;
+    }
+    .event {
+      padding: 9px 10px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: #121518;
+      white-space: pre-wrap;
+      overflow-wrap: anywhere;
+    }
+    .event.agent { border-color: #357969; }
+    .event.tool { border-color: #8b682b; }
+    .event.error { border-color: #9b4038; }
+    .event.ok { border-color: #4d8048; }
+    .approval-actions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+      margin-top: 9px;
+    }
+    .approval-actions button {
+      flex: 0 0 auto;
+      min-width: 84px;
+    }
+    .empty {
+      color: var(--muted);
+      font-size: 13px;
+    }
+    @media (min-width: 900px) {
+      main {
+        grid-template-columns: 330px minmax(0, 1fr);
+        align-items: start;
+      }
+      section.chat {
+        grid-column: 2;
+        grid-row: 1 / span 3;
+      }
+      #threads { max-height: 420px; }
+      #events { max-height: calc(100vh - 150px); }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>CodeWhale Mobile</h1>
+    <button id="refresh" title="Refresh threads">Refresh</button>
+  </header>
+
+  <main>
+    <section>
+      <div class="head">
+        <strong>Connection</strong>
+        <button id="save-token">Save</button>
+      </div>
+      <div class="body grid">
+        <input id="token" autocomplete="off" spellcheck="false" placeholder="Runtime token">
+        <div id="conn" class="status">Not connected</div>
+      </div>
+    </section>
+
+    <section>
+      <div class="head">
+        <strong>Threads</strong>
+        <button id="new-thread" class="primary">New</button>
+      </div>
+      <div class="body"><div id="threads"></div></div>
+    </section>
+
+    <section class="chat">
+      <div class="head">
+        <strong id="active-title">No thread selected</strong>
+        <span id="event-count" class="meta">0 events</span>
+      </div>
+      <div class="body"><div id="events"></div></div>
+    </section>
+
+    <section>
+      <div class="head">
+        <strong>Composer</strong>
+        <button id="interrupt" class="danger">Interrupt</button>
+      </div>
+      <div class="body grid">
+        <textarea id="prompt" spellcheck="true" placeholder="Message"></textarea>
+        <div class="row">
+          <label class="toggle"><input id="allow-shell" type="checkbox"> shell</label>
+          <label class="toggle"><input id="auto-approve" type="checkbox"> auto</label>
+          <label class="toggle"><input id="remember-approval" type="checkbox"> remember</label>
+        </div>
+        <div class="row">
+          <button id="send" class="primary">Send</button>
+          <button id="steer" class="warn">Steer</button>
+        </div>
+      </div>
+    </section>
+  </main>
+
+  <script>
+    const $ = (id) => document.getElementById(id);
+    const state = {
+      threadId: "",
+      activeTurnId: "",
+      source: null,
+      eventCount: 0
+    };
+
+    function setStatus(message, tone = "") {
+      const el = $("conn");
+      el.textContent = message;
+      el.className = "status" + (tone ? " " + tone : "");
+    }
+
+    function token() {
+      return $("token").value;
+    }
+
+    function takeTokenFromUrl() {
+      const params = new URLSearchParams(location.search);
+      const urlToken = params.get("token");
+      if (!urlToken) return;
+      localStorage.setItem("codewhale_runtime_token", urlToken);
+      params.delete("token");
+      const qs = params.toString();
+      history.replaceState(null, "", location.pathname + (qs ? "?" + qs : ""));
+    }
+
+    function headers(extra = {}) {
+      const out = Object.assign({ "Content-Type": "application/json" }, extra);
+      if (token()) out.Authorization = "Bearer " + token();
+      return out;
+    }
+
+    async function api(path, options = {}) {
+      const res = await fetch(path, Object.assign({}, options, {
+        headers: headers(options.headers || {})
+      }));
+      if (!res.ok) {
+        let detail = await res.text();
+        try {
+          const parsed = JSON.parse(detail);
+          detail = parsed.error?.message || detail;
+        } catch (_) {}
+        throw new Error(detail || ("HTTP " + res.status));
+      }
+      if (res.status === 204) return null;
+      return res.json();
+    }
+
+    function escapeHtml(raw) {
+      return String(raw).replace(/[&<>"']/g, (char) => ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        "\"": "&quot;",
+        "'": "&#039;"
+      }[char]));
+    }
+
+    function eventPayload(data) {
+      return data && typeof data === "object" && "payload" in data ? data.payload : data;
+    }
+
+    function eventText(name, data) {
+      const payload = eventPayload(data) || {};
+      if (name === "item.delta") return payload.delta || "";
+      if (name === "item.started") {
+        const tool = payload.tool;
+        if (tool) return "Tool started: " + tool.name + "\n" + JSON.stringify(tool.input || {}, null, 2);
+      }
+      if (name === "item.completed" || name === "item.failed") {
+        const item = payload.item || {};
+        return (name === "item.completed" ? "Completed: " : "Failed: ") + (item.summary || item.kind || "");
+      }
+      if (name === "approval.required") {
+        return "Approval required: " + (payload.tool_name || "") + "\n" + (payload.description || "");
+      }
+      if (name === "approval.decided") {
+        return "Approval " + (payload.decision || "decided") + ": " + (payload.approval_id || "");
+      }
+      if (name === "approval.timeout") {
+        return "Approval timed out: " + (payload.approval_id || "");
+      }
+      if (name === "sandbox.denied") {
+        return "Sandbox denied: " + (payload.tool_name || "") + "\n" + (payload.reason || "");
+      }
+      if (name === "turn.lifecycle") return "Turn status: " + (payload.status || "");
+      if (name === "turn.completed") return "Turn completed";
+      if (name === "coherence.state") return JSON.stringify(payload, null, 2);
+      return JSON.stringify(payload, null, 2);
+    }
+
+    function approvalInfo(name, data) {
+      if (name !== "approval.required") return null;
+      const payload = eventPayload(data) || {};
+      const approvalId = payload.approval_id || payload.id;
+      if (!approvalId) return null;
+      return { id: approvalId };
+    }
+
+    async function decideApproval(approvalId, decision, container) {
+      for (const button of container.querySelectorAll("button")) button.disabled = true;
+      const remember = $("remember-approval").checked;
+      try {
+        const result = await api("/v1/approvals/" + encodeURIComponent(approvalId), {
+          method: "POST",
+          body: JSON.stringify({ decision, remember })
+        });
+        const decided = result?.decision ?? decision;
+        container.innerHTML = "<span class='meta'>Decision sent: " + escapeHtml(decided) + "</span>";
+      } catch (err) {
+        for (const button of container.querySelectorAll("button")) button.disabled = false;
+        throw err;
+      }
+    }
+
+    function appendEvent(name, data) {
+      const text = eventText(name, data);
+      if (!text) return;
+      const item = document.createElement("div");
+      item.className = "event";
+      if (name === "item.delta") item.classList.add("agent");
+      if (name === "item.started" || name.includes("tool")) item.classList.add("tool");
+      if (name.includes("failed") || name.includes("denied") || name.includes("timeout")) item.classList.add("error");
+      if (name === "turn.completed" || name === "approval.decided") item.classList.add("ok");
+      item.innerHTML = "<div class='meta'>" + escapeHtml(name) + "</div>" + escapeHtml(text);
+
+      const approval = approvalInfo(name, data);
+      if (approval) {
+        const actions = document.createElement("div");
+        actions.className = "approval-actions";
+        const allow = document.createElement("button");
+        allow.className = "primary";
+        allow.textContent = "Allow";
+        allow.onclick = () => decideApproval(approval.id, "allow", actions)
+          .catch((err) => setStatus(err.message, "bad"));
+        const deny = document.createElement("button");
+        deny.className = "danger";
+        deny.textContent = "Deny";
+        deny.onclick = () => decideApproval(approval.id, "deny", actions)
+          .catch((err) => setStatus(err.message, "bad"));
+        actions.appendChild(allow);
+        actions.appendChild(deny);
+        item.appendChild(actions);
+      }
+
+      $("events").appendChild(item);
+      state.eventCount += 1;
+      $("event-count").textContent = state.eventCount + " events";
+      $("events").scrollTop = $("events").scrollHeight;
+    }
+
+    async function loadThreads() {
+      const threads = await api("/v1/threads/summary?limit=60&include_archived=false");
+      const list = $("threads");
+      list.innerHTML = "";
+      if (!threads || !threads.length) {
+        list.innerHTML = "<div class='empty'>No active threads.</div>";
+        return;
+      }
+      for (const thread of threads) {
+        const el = document.createElement("button");
+        el.className = "thread" + (thread.id === state.threadId ? " active" : "");
+        el.innerHTML =
+          "<div class='thread-title'>" + escapeHtml(thread.title || thread.id) + "</div>" +
+          "<div class='meta'>" + escapeHtml(thread.mode || "") + " / " +
+          escapeHtml(thread.model || "") + "</div>";
+        el.onclick = () => selectThread(thread.id, thread.title || thread.id);
+        list.appendChild(el);
+      }
+    }
+
+    async function newThread() {
+      const thread = await api("/v1/threads", {
+        method: "POST",
+        body: JSON.stringify({
+          mode: "agent",
+          allow_shell: $("allow-shell").checked,
+          trust_mode: false,
+          auto_approve: $("auto-approve").checked
+        })
+      });
+      await loadThreads();
+      selectThread(thread.id, thread.title || thread.id);
+    }
+
+    async function selectThread(id, title) {
+      state.threadId = id;
+      state.activeTurnId = "";
+      state.eventCount = 0;
+      $("event-count").textContent = "0 events";
+      $("active-title").textContent = title || id;
+      $("events").innerHTML = "";
+      if (state.source) state.source.close();
+      const qs = "?since_seq=0" + (token() ? "&token=" + encodeURIComponent(token()) : "");
+      const source = new EventSource("/v1/threads/" + encodeURIComponent(id) + "/events" + qs);
+      state.source = source;
+      const names = [
+        "thread.started",
+        "turn.started",
+        "turn.lifecycle",
+        "turn.steered",
+        "turn.interrupt_requested",
+        "turn.completed",
+        "item.started",
+        "item.delta",
+        "item.completed",
+        "item.failed",
+        "approval.required",
+        "approval.decided",
+        "approval.timeout",
+        "sandbox.denied",
+        "coherence.state"
+      ];
+      for (const name of names) {
+        source.addEventListener(name, (ev) => {
+          let data = {};
+          try { data = JSON.parse(ev.data || "{}"); } catch (_) {}
+          if (data.turn_id) state.activeTurnId = data.turn_id;
+          appendEvent(name, data);
+        });
+      }
+      source.onopen = () => setStatus("Connected", "ok");
+      source.onerror = () => setStatus("Event stream disconnected", "warn");
+      await loadThreads();
+    }
+
+    async function sendPrompt() {
+      if (!state.threadId) await newThread();
+      const prompt = $("prompt").value.trim();
+      if (!prompt) return;
+      const res = await api("/v1/threads/" + encodeURIComponent(state.threadId) + "/turns", {
+        method: "POST",
+        body: JSON.stringify({
+          prompt,
+          allow_shell: $("allow-shell").checked,
+          trust_mode: false,
+          auto_approve: $("auto-approve").checked
+        })
+      });
+      state.activeTurnId = res.turn?.id || state.activeTurnId;
+      $("prompt").value = "";
+      await loadThreads();
+    }
+
+    async function steerTurn() {
+      if (!state.threadId || !state.activeTurnId) throw new Error("No active turn");
+      const prompt = $("prompt").value.trim();
+      if (!prompt) return;
+      await api(
+        "/v1/threads/" + encodeURIComponent(state.threadId) +
+        "/turns/" + encodeURIComponent(state.activeTurnId) + "/steer",
+        { method: "POST", body: JSON.stringify({ prompt }) }
+      );
+      $("prompt").value = "";
+    }
+
+    async function interruptTurn() {
+      if (!state.threadId || !state.activeTurnId) throw new Error("No active turn");
+      await api(
+        "/v1/threads/" + encodeURIComponent(state.threadId) +
+        "/turns/" + encodeURIComponent(state.activeTurnId) + "/interrupt",
+        { method: "POST", body: "{}" }
+      );
+    }
+
+    async function boot() {
+      takeTokenFromUrl();
+      $("token").value = localStorage.getItem("codewhale_runtime_token") || "";
+      $("save-token").onclick = async () => {
+        localStorage.setItem("codewhale_runtime_token", token());
+        await loadThreads().catch((err) => setStatus(err.message, "bad"));
+      };
+      $("refresh").onclick = () => loadThreads().catch((err) => setStatus(err.message, "bad"));
+      $("new-thread").onclick = () => newThread().catch((err) => setStatus(err.message, "bad"));
+      $("send").onclick = () => sendPrompt().catch((err) => setStatus(err.message, "bad"));
+      $("steer").onclick = () => steerTurn().catch((err) => setStatus(err.message, "bad"));
+      $("interrupt").onclick = () => interruptTurn().catch((err) => setStatus(err.message, "bad"));
+      await loadThreads();
+      setStatus("Connected", "ok");
+    }
+
+    boot().catch((err) => setStatus(err.message, "bad"));
+  </script>
+</body>
+</html>
diff --git a/crates/tui/src/runtime_threads.rs b/crates/tui/src/runtime_threads.rs
index 1a08473d..d86b147a 100644
--- a/crates/tui/src/runtime_threads.rs
+++ b/crates/tui/src/runtime_threads.rs
@@ -833,6 +833,30 @@ impl RuntimeThreadManager {
         }
     }
 
+    pub async fn submit_user_input(
+        &self,
+        thread_id: &str,
+        input_id: &str,
+        response: crate::tools::user_input::UserInputResponse,
+    ) -> Result<bool> {
+        let active = self.active.lock().await;
+        let Some(state) = active.engines.get(thread_id) else {
+            bail!("thread '{thread_id}' not found");
+        };
+        state.engine.submit_user_input(input_id, response).await?;
+        Ok(true)
+    }
+
+    #[allow(dead_code)]
+    pub async fn cancel_user_input(&self, thread_id: &str, input_id: &str) -> Result<bool> {
+        let active = self.active.lock().await;
+        let Some(state) = active.engines.get(thread_id) else {
+            bail!("thread '{thread_id}' not found");
+        };
+        state.engine.cancel_user_input(input_id).await?;
+        Ok(true)
+    }
+
     #[allow(dead_code)]
     pub fn pending_approvals_count(&self) -> usize {
         self.pending_approvals
@@ -868,10 +892,10 @@ impl RuntimeThreadManager {
 
         {
             let mut active = self.active.lock().await;
-            if let Some(state) = active.engines.get_mut(thread_id) {
-                if let Some(turn) = state.active_turn.as_mut() {
-                    turn.auto_approve = true;
-                }
+            if let Some(state) = active.engines.get_mut(thread_id)
+                && let Some(turn) = state.active_turn.as_mut()
+            {
+                turn.auto_approve = true;
             }
         }
     }
@@ -1434,7 +1458,7 @@ impl RuntimeThreadManager {
 
             if let Some(assistant_text) = assistant_text {
                 let asst_summary = if assistant_text.len() > SUMMARY_LIMIT {
-                    format!("{}...", &assistant_text[..SUMMARY_LIMIT.saturating_sub(3)])
+                    crate::utils::truncate_with_ellipsis(&assistant_text, SUMMARY_LIMIT, "...")
                 } else {
                     assistant_text.clone()
                 };
@@ -1611,6 +1635,9 @@ impl RuntimeThreadManager {
         let allow_shell = req.allow_shell.unwrap_or(thread.allow_shell);
         let trust_mode = req.trust_mode.unwrap_or(thread.trust_mode);
         let auto_approve = req.auto_approve.unwrap_or(thread.auto_approve);
+        let show_thinking = crate::settings::Settings::load()
+            .unwrap_or_default()
+            .show_thinking;
 
         engine
             .send(Op::SendMessage {
@@ -1625,6 +1652,8 @@ impl RuntimeThreadManager {
                 trust_mode,
                 auto_approve,
                 translation_enabled: false,
+                show_thinking,
+                allowed_tools: None,
                 approval_mode: if auto_approve {
                     crate::tui::approval::ApprovalMode::Auto
                 } else {
@@ -1931,6 +1960,7 @@ impl RuntimeThreadManager {
             .lsp
             .clone()
             .map(crate::config::LspConfigToml::into_runtime);
+        let settings = crate::settings::Settings::load().unwrap_or_default();
         let engine_cfg = EngineConfig {
             model: thread.model.clone(),
             workspace: thread.workspace.clone(),
@@ -1939,9 +1969,15 @@ impl RuntimeThreadManager {
             notes_path: self.config.notes_path(),
             mcp_config_path: self.config.mcp_config_path(),
             skills_dir: self.config.skills_dir(),
-            instructions: self.config.instructions_paths(),
+            instructions: self
+                .config
+                .instructions_paths()
+                .into_iter()
+                .map(Into::into)
+                .collect(),
             project_context_pack_enabled: self.config.project_context_pack_enabled(),
             translation_enabled: false,
+            show_thinking: settings.show_thinking,
             max_steps: 100,
             max_subagents: self.config.max_subagents().clamp(1, MAX_SUBAGENTS),
             features: self.config.features(),
@@ -1952,6 +1988,7 @@ impl RuntimeThreadManager {
             ),
             todos: new_shared_todo_list(),
             plan_state: new_shared_plan_state(),
+            goal_state: crate::tools::goal::new_shared_goal_state(),
             max_spawn_depth: crate::tools::subagent::DEFAULT_MAX_SPAWN_DEPTH,
             network_policy,
             snapshots_enabled: self.config.snapshots_config().enabled,
@@ -1976,24 +2013,20 @@ impl RuntimeThreadManager {
             subagent_api_timeout: std::time::Duration::from_secs(
                 self.config.subagent_api_timeout_secs(),
             ),
+            prefer_bwrap: self.config.prefer_bwrap.unwrap_or(false),
             memory_enabled: self.config.memory_enabled(),
             memory_path: self.config.memory_path(),
             vision_config: self.config.vision_model_config(),
             strict_tool_mode: self.config.strict_tool_mode.unwrap_or(false),
             goal_objective: None,
-            locale_tag: crate::localization::resolve_locale(
-                &crate::settings::Settings::load().unwrap_or_default().locale,
-            )
-            .tag()
-            .to_string(),
+            allowed_tools: None,
+            locale_tag: crate::localization::resolve_locale(&settings.locale)
+                .tag()
+                .to_string(),
             workshop: self.config.workshop.clone(),
-            search_provider: self
-                .config
-                .search
-                .as_ref()
-                .and_then(|s| s.provider)
-                .unwrap_or_default(),
+            search_provider: self.config.search_provider(),
             search_api_key: self.config.search.as_ref().and_then(|s| s.api_key.clone()),
+            tools_always_load: self.config.tools_always_load(),
         };
 
         let engine = spawn_engine(engine_cfg, &self.config);
@@ -2782,6 +2815,19 @@ impl RuntimeThreadManager {
                         }
                     }
                 }
+                EngineEvent::UserInputRequired { id, request } => {
+                    self.emit_event(
+                        &thread_id,
+                        Some(&turn_id),
+                        None,
+                        "user_input.required",
+                        json!({
+                            "id": id,
+                            "request": request,
+                        }),
+                    )
+                    .await?;
+                }
                 EngineEvent::Status { message } => {
                     let item = TurnItemRecord {
                         schema_version: CURRENT_RUNTIME_SCHEMA_VERSION,
@@ -4170,6 +4216,7 @@ mod tests {
                 id: "tool_stale".to_string(),
                 tool_name: "exec_command".to_string(),
                 description: "stale approval".to_string(),
+                input: serde_json::json!({}),
             })
             .await?;
 
@@ -4243,6 +4290,7 @@ mod tests {
                 id: "tool_external_allow".to_string(),
                 tool_name: "exec_command".to_string(),
                 description: "external allow".to_string(),
+                input: serde_json::json!({}),
             })
             .await?;
 
@@ -4320,6 +4368,7 @@ mod tests {
                 id: "tool_external_deny".to_string(),
                 tool_name: "exec_command".to_string(),
                 description: "external deny".to_string(),
+                input: serde_json::json!({}),
             })
             .await?;
 
@@ -4506,6 +4555,7 @@ mod tests {
                 id: "tool_remember".to_string(),
                 tool_name: "exec_command".to_string(),
                 description: "remember=true".to_string(),
+                input: serde_json::json!({}),
             })
             .await?;
 
diff --git a/crates/tui/src/sandbox/bwrap.rs b/crates/tui/src/sandbox/bwrap.rs
new file mode 100644
index 00000000..1db43b0e
--- /dev/null
+++ b/crates/tui/src/sandbox/bwrap.rs
@@ -0,0 +1,129 @@
+//! Bubblewrap (bwrap) passthrough for Linux sandbox (#2184).
+//!
+//! Bubblewrap is a setuid-less container runtime used by Flatpak and other
+//! projects. It creates a new mount namespace with configurable bind mounts,
+//! providing filesystem isolation without requiring root privileges.
+//!
+//! # How it works
+//!
+//! When `/usr/bin/bwrap` is present AND the config key `[sandbox] prefer_bwrap`
+//! is set to `true`, exec_shell commands are routed through bwrap instead of
+//! relying solely on Landlock. The bwrap invocation looks like:
+//!
+//! ```text
+//! bwrap \
+//!   --ro-bind / / \
+//!   --bind <cwd> <cwd> \
+//!   --chdir <cwd> \
+//!   --unshare-all \
+//!   -- <program> <args>
+//! ```
+//!
+//! This creates a read-only view of the entire filesystem with write access
+//! limited to the working directory.
+//!
+//! # Important
+//!
+//! We do NOT vendor bwrap. The user must install it themselves:
+//!
+//! - Ubuntu/Debian: `apt install bubblewrap`
+//! - Fedora: `dnf install bubblewrap`
+//! - Arch: `pacman -S bubblewrap`
+//!
+//! If bwrap is not installed, we fall back to Landlock.
+
+/// Canonical path to the bubblewrap binary.
+#[cfg(target_os = "linux")]
+pub const BWRAP_PATH: &str = "/usr/bin/bwrap";
+
+/// Check if bubblewrap is installed and executable.
+#[cfg(target_os = "linux")]
+pub fn is_available() -> bool {
+    std::path::Path::new(BWRAP_PATH).exists()
+}
+
+#[cfg(not(target_os = "linux"))]
+pub fn is_available() -> bool {
+    false
+}
+
+/// Build a bwrap command that wraps the given program and arguments.
+///
+/// The returned command vector is suitable for use as `ExecEnv.command` —
+/// it replaces the normal program+args with a bwrap invocation that sets
+/// up a read-only root filesystem with write access only to the specified
+/// working directory.
+///
+/// # Arguments
+///
+/// - `cwd` — working directory that gets writable bind-mount
+/// - `program` — the program to run inside the container
+/// - `args` — arguments to pass to the program
+///
+/// # Returns
+///
+/// A `Vec<String>` representing the full bwrap invocation.
+#[cfg(target_os = "linux")]
+pub fn build_bwrap_command(cwd: &std::path::Path, program: &str, args: &[String]) -> Vec<String> {
+    let mut cmd: Vec<String> = Vec::with_capacity(10 + args.len());
+
+    cmd.push(BWRAP_PATH.to_string());
+
+    // Read-only bind-mount the entire root filesystem.
+    cmd.push("--ro-bind".to_string());
+    cmd.push("/".to_string());
+    cmd.push("/".to_string());
+
+    // Bind-mount the working directory with read-write access.
+    let cwd_str = cwd.to_string_lossy().to_string();
+    cmd.push("--bind".to_string());
+    cmd.push(cwd_str.clone());
+    cmd.push(cwd_str.clone());
+
+    // Change to the working directory inside the container.
+    cmd.push("--chdir".to_string());
+    cmd.push(cwd_str);
+
+    // Unshare all namespaces for maximum isolation.
+    cmd.push("--unshare-all".to_string());
+
+    // Separator between bwrap args and the command to run.
+    cmd.push("--".to_string());
+
+    // The actual program and its arguments.
+    cmd.push(program.to_string());
+    cmd.extend(args.iter().cloned());
+
+    cmd
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_is_available_does_not_panic() {
+        let _ = is_available();
+    }
+
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn test_build_bwrap_command_structure() {
+        let cwd = std::path::Path::new("/home/user/project");
+        let cmd = build_bwrap_command(cwd, "sh", &["-c".to_string(), "echo hi".to_string()]);
+
+        // Should start with bwrap
+        assert_eq!(cmd[0], "/usr/bin/bwrap");
+
+        // Should have ro-bind for root
+        assert!(cmd.contains(&"--ro-bind".to_string()));
+
+        // Should have --chdir
+        assert!(cmd.contains(&"--chdir".to_string()));
+
+        // Should end with the command
+        assert_eq!(cmd[cmd.len() - 1], "echo hi");
+        assert_eq!(cmd[cmd.len() - 2], "-c");
+        assert_eq!(cmd[cmd.len() - 3], "sh");
+    }
+}
diff --git a/crates/tui/src/sandbox/landlock.rs b/crates/tui/src/sandbox/landlock.rs
index 7670d65b..4a083ea3 100644
--- a/crates/tui/src/sandbox/landlock.rs
+++ b/crates/tui/src/sandbox/landlock.rs
@@ -290,18 +290,32 @@ pub fn create_landlock_wrapper(
     cmd
 }
 
-/// Detect if a failure was caused by Landlock denial
+/// Detect if a failure was caused by Landlock or seccomp denial.
+///
+/// Checks both Landlock-specific patterns (EACCES/EPERM) and seccomp-specific
+/// patterns (Bad system call / SIGSYS). Seccomp violations are reported through
+/// the same `was_denied` path so callers don't need to distinguish which layer
+/// blocked the operation.
 #[cfg(target_os = "linux")]
 pub fn detect_denial(exit_code: i32, stderr: &str) -> bool {
     if exit_code == 0 {
         return false;
     }
 
-    // Landlock denials typically result in EACCES or EPERM
-    stderr.contains("Permission denied")
+    // Landlock denials typically result in EACCES or EPERM.
+    let landlock_denial = stderr.contains("Permission denied")
         || stderr.contains("Operation not permitted")
         || stderr.contains("EACCES")
-        || stderr.contains("EPERM")
+        || stderr.contains("EPERM");
+
+    // Seccomp denials (#2182): SIGSYS (exit code 31 or "Bad system call").
+    let seccomp_denial = exit_code == 31
+        || stderr.contains("Bad system call")
+        || stderr.contains("bad system call")
+        || stderr.contains("SIGSYS")
+        || stderr.contains("seccomp");
+
+    landlock_denial || seccomp_denial
 }
 
 // Stub implementations for non-Linux platforms
diff --git a/crates/tui/src/sandbox/mod.rs b/crates/tui/src/sandbox/mod.rs
index 508e3bd6..22864c60 100644
--- a/crates/tui/src/sandbox/mod.rs
+++ b/crates/tui/src/sandbox/mod.rs
@@ -30,6 +30,7 @@
 pub mod backend;
 pub mod opensandbox;
 pub mod policy;
+pub mod process_hardening;
 
 #[cfg(target_os = "macos")]
 pub mod seatbelt;
@@ -37,6 +38,12 @@ pub mod seatbelt;
 #[cfg(target_os = "linux")]
 pub mod landlock;
 
+#[cfg(target_os = "linux")]
+pub mod seccomp;
+
+#[cfg(target_os = "linux")]
+pub mod bwrap;
+
 #[cfg(target_os = "windows")]
 pub mod windows;
 
@@ -79,20 +86,28 @@ pub struct CommandSpec {
 impl CommandSpec {
     /// Create a `CommandSpec` for running a shell command via the platform shell.
     pub fn shell(command: &str, cwd: PathBuf, timeout: Duration) -> Self {
+        let dispatcher = crate::shell_dispatcher::global_dispatcher();
+
         #[cfg(windows)]
         let (program, args) = {
-            // Force UTF-8 output on Windows by running `chcp 65001` before the
-            // actual command. Without this, subprocesses output in the system's
-            // ANSI code page (e.g. GBK for Chinese locales), causing garbled
-            // text in the shell output panel. See issue #982.
-            let cmd = format!("chcp 65001 >NUL & {command}");
-            ("cmd".to_string(), vec!["/C".to_string(), cmd])
+            // Force UTF-8 output. cmd.exe uses chcp; PowerShell sets the
+            // console output encoding directly. See issue #982.
+            let kind = dispatcher.kind();
+            let cmd = if matches!(
+                kind,
+                crate::shell_dispatcher::ShellKind::Pwsh
+                    | crate::shell_dispatcher::ShellKind::WindowsPowerShell
+            ) {
+                format!("[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; {command}")
+            } else if matches!(kind, crate::shell_dispatcher::ShellKind::Cmd) {
+                format!("chcp 65001 >NUL & {command}")
+            } else {
+                command.to_string()
+            };
+            dispatcher.build_command_parts(&cmd)
         };
         #[cfg(not(windows))]
-        let (program, args) = (
-            "sh".to_string(),
-            vec!["-c".to_string(), command.to_string()],
-        );
+        let (program, args) = dispatcher.build_command_parts(command);
 
         Self {
             program,
@@ -144,9 +159,24 @@ impl CommandSpec {
 
     /// Get the original command as a single string (for display).
     pub fn display_command(&self) -> String {
-        if self.program == "sh" && self.args.len() == 2 && self.args[0] == "-c" {
+        if self.args.len() == 2
+            && self.args[0] == "-c"
+            && matches!(
+                self.program.as_str(),
+                "sh" | "bash" | "/bin/sh" | "/bin/bash" | "/usr/bin/sh" | "/usr/bin/bash"
+            )
+        {
             // For shell commands, show the actual command
             self.args[1].clone()
+        } else if self.args.len() == 2
+            && self.args[0] == "-c"
+            && !self.program.eq_ignore_ascii_case("cmd")
+            && !self.program.eq_ignore_ascii_case("pwsh")
+            && !self.program.eq_ignore_ascii_case("pwsh.exe")
+            && !self.program.eq_ignore_ascii_case("powershell")
+            && !self.program.eq_ignore_ascii_case("powershell.exe")
+        {
+            self.args[1].clone()
         } else if self.program.eq_ignore_ascii_case("cmd")
             && self.args.len() == 2
             && self.args[0].eq_ignore_ascii_case("/C")
@@ -157,6 +187,21 @@ impl CommandSpec {
             raw.strip_prefix("chcp 65001 >NUL & ")
                 .unwrap_or(raw)
                 .to_string()
+        } else if {
+            let program = self.program.to_ascii_lowercase();
+            program == "pwsh"
+                || program == "pwsh.exe"
+                || program == "powershell"
+                || program == "powershell.exe"
+        } && self.args.len() >= 3
+            && self.args[0].eq_ignore_ascii_case("-NoProfile")
+            && self.args[1].eq_ignore_ascii_case("-Command")
+        {
+            // Strip the PowerShell encoding prefix.
+            let raw = &self.args[2];
+            raw.strip_prefix("[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; ")
+                .unwrap_or(raw)
+                .to_string()
         } else {
             // For other commands, join program and args
             let mut parts = vec![self.program.clone()];
@@ -296,17 +341,34 @@ pub struct SandboxManager {
     /// Force a specific sandbox type (for testing).
     #[allow(dead_code)]
     forced_sandbox: Option<SandboxType>,
+
+    /// When true and bwrap is available on Linux, route commands through
+    /// bubblewrap instead of Landlock alone (#2184).
+    prefer_bwrap: bool,
 }
 
 impl SandboxManager {
     /// Create a new `SandboxManager`.
     pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Create a new `SandboxManager` with bwrap preference (#2184).
+    ///
+    /// When `prefer_bwrap` is true and `/usr/bin/bwrap` is present on Linux,
+    /// exec_shell commands will be routed through bubblewrap.
+    pub fn with_bwrap_preference(prefer_bwrap: bool) -> Self {
         Self {
-            sandbox_available: None,
-            forced_sandbox: None,
+            prefer_bwrap,
+            ..Self::default()
         }
     }
 
+    /// Set the bwrap preference (#2184).
+    pub fn set_prefer_bwrap(&mut self, prefer: bool) {
+        self.prefer_bwrap = prefer;
+    }
+
     /// Check if sandboxing is available.
     pub fn is_available(&mut self) -> bool {
         if let Some(available) = self.sandbox_available {
@@ -349,7 +411,7 @@ impl SandboxManager {
             SandboxType::MacosSeatbelt => Self::prepare_seatbelt(spec),
 
             #[cfg(target_os = "linux")]
-            SandboxType::LinuxLandlock => Self::prepare_landlock(spec),
+            SandboxType::LinuxLandlock => self.prepare_landlock(spec),
 
             #[cfg(target_os = "windows")]
             SandboxType::Windows => Self::prepare_windows(spec),
@@ -402,26 +464,35 @@ impl SandboxManager {
 
     /// Prepare a Landlock-sandboxed execution environment (Linux).
     ///
-    /// Note: Landlock restricts the current process, so for subprocess sandboxing
-    /// we would need a helper binary. For now, this prepares the environment with
-    /// appropriate markers but doesn't actually apply Landlock (would need helper).
+    /// If `prefer_bwrap` is set and `/usr/bin/bwrap` is available, routes the
+    /// command through bubblewrap for stronger filesystem isolation (#2184).
+    /// Otherwise falls back to Landlock markers.
     #[cfg(target_os = "linux")]
-    fn prepare_landlock(spec: &CommandSpec) -> ExecEnv {
-        // Build the original command
+    fn prepare_landlock(&self, spec: &CommandSpec) -> ExecEnv {
+        // Check if bwrap passthrough should be used (#2184).
+        if self.prefer_bwrap && bwrap::is_available() {
+            let command = bwrap::build_bwrap_command(&spec.cwd, &spec.program, &spec.args);
+
+            let mut env = spec.env.clone();
+            env.insert("DEEPSEEK_SANDBOX".to_string(), "bwrap".to_string());
+
+            return ExecEnv {
+                command,
+                cwd: spec.cwd.clone(),
+                env,
+                timeout: spec.timeout,
+                sandbox_type: SandboxType::LinuxLandlock,
+                policy: spec.sandbox_policy.clone(),
+            };
+        }
+
+        // Fall back to Landlock (marker only — full implementation needs a helper).
         let mut command = vec![spec.program.clone()];
         command.extend(spec.args.clone());
 
-        // Add sandbox indicator to environment
         let mut env = spec.env.clone();
         env.insert("DEEPSEEK_SANDBOX".to_string(), "landlock".to_string());
 
-        // Note: Full Landlock implementation would use a helper binary that:
-        // 1. Sets up the Landlock ruleset based on policy
-        // 2. Applies restrictions to itself
-        // 3. Execs the target command
-        //
-        // For now, we just mark that Landlock would be used
-
         ExecEnv {
             command,
             cwd: spec.cwd.clone(),
@@ -509,7 +580,15 @@ impl SandboxManager {
 
             #[cfg(target_os = "linux")]
             SandboxType::LinuxLandlock => {
-                if stderr.contains("Permission denied") {
+                // Seccomp patterns checked first because they are more specific (#2182).
+                if stderr.contains("Bad system call")
+                    || stderr.contains("bad system call")
+                    || stderr.contains("SIGSYS")
+                    || stderr.contains("seccomp")
+                {
+                    "Seccomp blocked a disallowed system call (e.g., ptrace, mount, kexec)."
+                        .to_string()
+                } else if stderr.contains("Permission denied") {
                     "Landlock blocked access. The command tried to access a restricted path."
                         .to_string()
                 } else {
@@ -543,35 +622,28 @@ impl SandboxManager {
 mod tests {
     use super::*;
 
-    fn expected_shell_command(command: &str) -> Vec<String> {
-        #[cfg(windows)]
-        {
-            vec![
-                "cmd".to_string(),
-                "/C".to_string(),
-                format!("chcp 65001 >NUL & {command}"),
-            ]
-        }
-        #[cfg(not(windows))]
-        {
-            vec!["sh".to_string(), "-c".to_string(), command.to_string()]
-        }
-    }
-
     #[test]
     fn test_command_spec_shell() {
         let spec = CommandSpec::shell("echo hello", PathBuf::from("/tmp"), Duration::from_secs(30));
 
-        #[cfg(windows)]
-        {
-            assert_eq!(spec.program, "cmd");
-            assert_eq!(spec.args, vec!["/C", "chcp 65001 >NUL & echo hello"]);
-        }
-        #[cfg(not(windows))]
-        {
-            assert_eq!(spec.program, "sh");
-            assert_eq!(spec.args, vec!["-c", "echo hello"]);
-        }
+        // Program and args depend on the detected shell.
+        assert!(!spec.program.is_empty(), "program must not be empty");
+        assert!(!spec.args.is_empty(), "args must not be empty");
+        assert_eq!(spec.display_command(), "echo hello");
+    }
+
+    #[test]
+    fn test_command_spec_shell_custom_posix_path_display() {
+        let spec = CommandSpec {
+            program: "/bin/zsh".to_string(),
+            args: vec!["-c".to_string(), "echo hello".to_string()],
+            cwd: PathBuf::from("/tmp"),
+            env: HashMap::new(),
+            timeout: Duration::from_secs(30),
+            sandbox_policy: SandboxPolicy::default(),
+            justification: None,
+        };
+
         assert_eq!(spec.display_command(), "echo hello");
     }
 
@@ -585,19 +657,28 @@ mod tests {
         let cmd = r#"git commit -m "feat: complete sub-pages""#;
         let spec = CommandSpec::shell(cmd, PathBuf::from("/tmp"), Duration::from_secs(30));
 
-        #[cfg(windows)]
-        {
-            assert_eq!(spec.program, "cmd");
+        let dispatcher = crate::shell_dispatcher::global_dispatcher();
+        assert_eq!(spec.program, dispatcher.kind().binary());
+        if dispatcher.kind().is_powershell() {
             assert_eq!(
                 spec.args,
-                vec!["/C".to_string(), format!("chcp 65001 >NUL & {cmd}")]
+                vec![
+                    dispatcher.kind().command_flag().to_string(),
+                    "-Command".to_string(),
+                    format!("[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; {cmd}")
+                ]
             );
-        }
-        #[cfg(not(windows))]
-        {
-            assert_eq!(spec.program, "sh");
-            assert_eq!(spec.args, vec!["-c".to_string(), cmd.to_string()]);
-            // The quoted message is intact in a single argv slot — `sh -c`
+        } else {
+            let expected = if matches!(dispatcher.kind(), crate::shell_dispatcher::ShellKind::Cmd) {
+                vec!["/C".to_string(), format!("chcp 65001 >NUL & {cmd}")]
+            } else {
+                vec![
+                    dispatcher.kind().command_flag().to_string(),
+                    cmd.to_string(),
+                ]
+            };
+            assert_eq!(spec.args, expected);
+            // The quoted message is intact in a single argv slot — shell `-c`
             // performs POSIX tokenization, yielding the correct argv:
             // ["git","commit","-m","feat: complete sub-pages"].
             assert_eq!(spec.args.len(), 2);
@@ -659,9 +740,39 @@ mod tests {
             .with_policy(SandboxPolicy::DangerFullAccess);
 
         let env = manager.prepare(&spec);
+        let dispatcher = crate::shell_dispatcher::global_dispatcher();
 
         assert_eq!(env.sandbox_type, SandboxType::None);
-        assert_eq!(env.command, expected_shell_command("echo test"));
+        if dispatcher.kind().is_powershell() {
+            assert_eq!(
+                env.command,
+                vec![
+                    dispatcher.kind().binary().to_string(),
+                    dispatcher.kind().command_flag().to_string(),
+                    "-Command".to_string(),
+                    "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; echo test"
+                        .to_string(),
+                ]
+            );
+        } else if matches!(dispatcher.kind(), crate::shell_dispatcher::ShellKind::Cmd) {
+            assert_eq!(
+                env.command,
+                vec![
+                    dispatcher.kind().binary().to_string(),
+                    "/C".to_string(),
+                    "chcp 65001 >NUL & echo test".to_string(),
+                ]
+            );
+        } else {
+            assert_eq!(
+                env.command,
+                vec![
+                    dispatcher.kind().binary().to_string(),
+                    dispatcher.kind().command_flag().to_string(),
+                    "echo test".to_string(),
+                ]
+            );
+        }
         assert!(!env.is_sandboxed());
     }
 
@@ -694,4 +805,130 @@ mod tests {
         #[cfg(target_os = "macos")]
         assert_eq!(format!("{}", SandboxType::MacosSeatbelt), "macos-seatbelt");
     }
+
+    // ── Parity tests (#2187) ──────────────────────────────────────────────
+
+    #[test]
+    fn test_parity_platform_sandbox_detection() {
+        let sandbox_type = get_platform_sandbox();
+        let available = is_sandbox_available();
+        if available {
+            assert!(sandbox_type.is_some());
+        }
+    }
+
+    #[test]
+    #[cfg(target_os = "macos")]
+    fn test_parity_macos_seatbelt_available() {
+        let st = get_platform_sandbox();
+        assert!(matches!(st, Some(SandboxType::MacosSeatbelt)));
+    }
+
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn test_parity_linux_landlock_available() {
+        let st = get_platform_sandbox();
+        assert!(matches!(st, Some(SandboxType::LinuxLandlock)));
+    }
+
+    #[test]
+    fn test_parity_denial_zero_exit_never_denied() {
+        assert!(!SandboxManager::was_denied(
+            SandboxType::None,
+            0,
+            "anything"
+        ));
+        #[cfg(target_os = "macos")]
+        assert!(!SandboxManager::was_denied(
+            SandboxType::MacosSeatbelt,
+            0,
+            ""
+        ));
+        #[cfg(target_os = "linux")]
+        assert!(!SandboxManager::was_denied(
+            SandboxType::LinuxLandlock,
+            0,
+            ""
+        ));
+        #[cfg(target_os = "windows")]
+        assert!(!SandboxManager::was_denied(SandboxType::Windows, 0, ""));
+    }
+
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn test_parity_seccomp_sigsys_detected() {
+        assert!(SandboxManager::was_denied(
+            SandboxType::LinuxLandlock,
+            31,
+            ""
+        ));
+        assert!(SandboxManager::was_denied(
+            SandboxType::LinuxLandlock,
+            1,
+            "Bad system call"
+        ));
+    }
+
+    #[test]
+    #[cfg(target_os = "macos")]
+    fn test_parity_seatbelt_file_write_detected() {
+        // Seatbelt patterns use "Sandbox: <cmd> denied <operation>" format.
+        assert!(SandboxManager::was_denied(
+            SandboxType::MacosSeatbelt,
+            1,
+            "Sandbox: ls denied file-write*"
+        ));
+        assert!(SandboxManager::was_denied(
+            SandboxType::MacosSeatbelt,
+            1,
+            "Operation not permitted"
+        ));
+    }
+
+    #[test]
+    fn test_parity_manager_default_no_bwrap() {
+        let manager = SandboxManager::default();
+        let spec = CommandSpec::shell("true", PathBuf::from("/tmp"), Duration::from_secs(5))
+            .with_policy(SandboxPolicy::default());
+        let env = manager.prepare(&spec);
+        #[cfg(target_os = "linux")]
+        {
+            let marker = env.env.get("DEEPSEEK_SANDBOX");
+            assert!(marker.is_none_or(|v| v != "bwrap"));
+        }
+        let _ = env;
+    }
+
+    #[test]
+    fn test_parity_manager_with_bwrap() {
+        let manager = SandboxManager::with_bwrap_preference(true);
+        let spec = CommandSpec::shell("true", PathBuf::from("/tmp"), Duration::from_secs(5))
+            .with_policy(SandboxPolicy::default());
+        let env = manager.prepare(&spec);
+        #[cfg(target_os = "linux")]
+        {
+            if crate::sandbox::bwrap::is_available() {
+                let marker = env.env.get("DEEPSEEK_SANDBOX");
+                assert_eq!(marker.map(String::as_str), Some("bwrap"));
+            }
+        }
+        let _ = env;
+    }
+
+    #[test]
+    fn test_parity_exec_env_for_all_policies() {
+        let manager = SandboxManager::new();
+        let policies = [
+            SandboxPolicy::DangerFullAccess,
+            SandboxPolicy::ReadOnly,
+            SandboxPolicy::workspace_with_network(),
+            SandboxPolicy::default(),
+        ];
+        for policy in &policies {
+            let spec = CommandSpec::shell("true", PathBuf::from("/tmp"), Duration::from_secs(5))
+                .with_policy(policy.clone());
+            let env = manager.prepare(&spec);
+            assert_eq!(env.policy, *policy);
+        }
+    }
 }
diff --git a/crates/tui/src/sandbox/policy.rs b/crates/tui/src/sandbox/policy.rs
index 1ea5dc55..f49113bc 100644
--- a/crates/tui/src/sandbox/policy.rs
+++ b/crates/tui/src/sandbox/policy.rs
@@ -7,8 +7,12 @@
 //! tightly controlled workspace-only write access.
 
 use serde::{Deserialize, Serialize};
+use std::io;
 use std::path::{Path, PathBuf};
 
+use super::{CommandSpec, ExecEnv};
+use crate::command_safety::SafetyLevel;
+
 /// Determines execution restrictions for shell commands.
 ///
 /// The sandbox policy controls filesystem access, network access, and other
@@ -256,6 +260,57 @@ impl WritableRoot {
     }
 }
 
+/// Unified trait for platform-specific sandbox executors (#2186).
+///
+/// Each platform module (seatbelt, landlock, windows) provides an
+/// implementation of this trait. The `SandboxManager` dispatches through
+/// the trait instead of calling platform-specific functions directly.
+pub trait SandboxExecutor {
+    /// Prepare a sandboxed execution environment from a command spec.
+    ///
+    /// Returns the transformed command, environment, and sandbox metadata
+    /// needed to spawn the process.
+    fn prepare(&self, spec: &CommandSpec) -> io::Result<ExecEnv>;
+
+    /// Check if a command failure was caused by sandbox denial.
+    fn was_denied(&self, exit_code: i32, stderr: &str) -> bool;
+
+    /// Get a human-readable description of why the sandbox blocked the command.
+    fn denial_message(&self, stderr: &str) -> String;
+
+    /// Returns the type of sandbox this executor provides.
+    fn sandbox_type(&self) -> super::SandboxType;
+}
+
+/// Map a command safety classification to the appropriate sandbox policy (#2186).
+///
+/// - `Safe` / `WorkspaceSafe` → use the default sandbox policy
+/// - `RequiresApproval` → user must approve before execution (handled by caller)
+/// - `Dangerous` → blocked unless in YOLO mode with trust
+pub fn map_safety_level_to_behavior(
+    level: SafetyLevel,
+    default_policy: &SandboxPolicy,
+) -> SandboxPolicyBehavior {
+    match level {
+        SafetyLevel::Safe | SafetyLevel::WorkspaceSafe => {
+            SandboxPolicyBehavior::Sandboxed(default_policy.clone())
+        }
+        SafetyLevel::RequiresApproval => SandboxPolicyBehavior::RequiresApproval,
+        SafetyLevel::Dangerous => SandboxPolicyBehavior::Blocked,
+    }
+}
+
+/// Behavior decision for a sandboxed command based on safety level.
+#[derive(Debug, Clone)]
+pub enum SandboxPolicyBehavior {
+    /// Execute with the given sandbox policy.
+    Sandboxed(SandboxPolicy),
+    /// User approval required before execution.
+    RequiresApproval,
+    /// Block execution entirely (unless YOLO+trust).
+    Blocked,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -308,6 +363,33 @@ mod tests {
         assert!(!root.is_path_writable(Path::new("/project/.deepseek/config")));
     }
 
+    #[test]
+    fn test_safety_level_mapping() {
+        let default = SandboxPolicy::default();
+
+        // Safe commands get sandboxed
+        assert!(matches!(
+            map_safety_level_to_behavior(SafetyLevel::Safe, &default),
+            SandboxPolicyBehavior::Sandboxed(_)
+        ));
+        assert!(matches!(
+            map_safety_level_to_behavior(SafetyLevel::WorkspaceSafe, &default),
+            SandboxPolicyBehavior::Sandboxed(_)
+        ));
+
+        // RequiresApproval gets RequiresApproval
+        assert!(matches!(
+            map_safety_level_to_behavior(SafetyLevel::RequiresApproval, &default),
+            SandboxPolicyBehavior::RequiresApproval
+        ));
+
+        // Dangerous gets Blocked
+        assert!(matches!(
+            map_safety_level_to_behavior(SafetyLevel::Dangerous, &default),
+            SandboxPolicyBehavior::Blocked
+        ));
+    }
+
     #[test]
     fn test_policy_serialization() {
         let policy = SandboxPolicy::WorkspaceWrite {
diff --git a/crates/tui/src/sandbox/process_hardening.rs b/crates/tui/src/sandbox/process_hardening.rs
new file mode 100644
index 00000000..0c95b48a
--- /dev/null
+++ b/crates/tui/src/sandbox/process_hardening.rs
@@ -0,0 +1,137 @@
+//! Process hardening for Linux sandbox defense-in-depth (#2183).
+//!
+//! This module applies kernel-level restrictions to the codewhale-tui process
+//! itself. Unlike Landlock/seccomp which restrict child processes spawned for
+//! shell commands, these hardening measures protect the *parent* TUI process
+//! from information leaks and privilege-escalation vectors.
+//!
+//! # Ordering constraints
+//!
+//! `apply_process_hardening()` MUST be called **before** the Tokio runtime is
+//! booted and **before** any worker threads are spawned. The reasons:
+//!
+//! 1. `PR_SET_DUMPABLE` — once set to 0, the process cannot be ptraced and
+//!    `/proc/self/` becomes root-owned. This must happen before any threads
+//!    exist, because the kernel applies dumpable state per-thread-group and
+//!    changing it after threads are live can race with `/proc` lookups.
+//!
+//! 2. `PR_SET_NO_NEW_PRIVS` — prevents the process and all descendants from
+//!    ever gaining new privileges via setuid/setgid/fscaps. This is
+//!    irreversible and must be applied before executing any helper binaries or
+//!    subprocesses that might (incorrectly) rely on privilege boundaries.
+//!
+//! 3. `RLIMIT_CORE` — disables core dumps so that sensitive in-memory data
+//!    (API keys, tokens, prompt content) is never written to disk on a crash.
+//!    Setting this before any data is loaded into memory is the safest posture.
+//!
+//! # Platform support
+//!
+//! These hardening measures are Linux-only (they use `prctl` and `setrlimit`
+//! from the `libc` crate). On non-Linux platforms, `apply_process_hardening()`
+//! is a no-op that logs a debug-level message.
+
+/// Apply process-level hardening measures.
+///
+/// On Linux, this:
+/// - Sets `PR_SET_DUMPABLE` to 0 (prevents ptrace, core dumps)
+/// - Sets `PR_SET_NO_NEW_PRIVS` to 1 (irreversible no-new-privileges)
+/// - Sets `RLIMIT_CORE` to 0 (disables core dumps)
+///
+/// On non-Linux platforms this is a no-op.
+///
+/// # Panics
+///
+/// Does NOT panic. Failures are logged via `tracing::warn` because the
+/// hardening is defense-in-depth — the sandbox still protects child processes
+/// even if these prctls fail (e.g., in a container where some are restricted).
+pub fn apply_process_hardening() {
+    #[cfg(target_os = "linux")]
+    {
+        apply_linux_hardening();
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        tracing::debug!("Process hardening skipped: not on Linux");
+    }
+}
+
+/// Linux-specific hardening implementation.
+#[cfg(target_os = "linux")]
+fn apply_linux_hardening() {
+    // ── PR_SET_DUMPABLE = 0 ────────────────────────────────────────────────
+    //
+    // When dumpable is 0:
+    // - The process cannot be ptraced by non-root
+    // - /proc/<pid>/ becomes owned by root:root (mode 0400)
+    // - No core dumps are produced
+    //
+    // Pattern from openai/codex codex-rs/codex-sandbox/src/linux.rs; reimplemented.
+    //
+    // Safety: prctl with PR_SET_DUMPABLE modifies only the calling process.
+    let result = unsafe { libc::prctl(libc::PR_SET_DUMPABLE, 0i64, 0i64, 0i64, 0i64) };
+    if result != 0 {
+        let err = std::io::Error::last_os_error();
+        tracing::warn!(
+            "PR_SET_DUMPABLE failed ({}); continuing without this hardening",
+            err
+        );
+    } else {
+        tracing::debug!("PR_SET_DUMPABLE=0 applied");
+    }
+
+    // ── PR_SET_NO_NEW_PRIVS = 1 ────────────────────────────────────────────
+    //
+    // Once set, neither this process nor any descendant can ever gain new
+    // privileges via setuid, setgid, file capabilities, or LSMs like SELinux
+    // transitions. This is the strongest anti-escalation primitive the kernel
+    // offers.
+    //
+    // Pattern from openai/codex codex-rs/codex-sandbox/src/linux.rs; reimplemented.
+    //
+    // Safety: prctl with PR_SET_NO_NEW_PRIVS modifies only the calling process
+    // and its future descendants.
+    let result = unsafe { libc::prctl(libc::PR_SET_NO_NEW_PRIVS, 1i64, 0i64, 0i64, 0i64) };
+    if result != 0 {
+        let err = std::io::Error::last_os_error();
+        tracing::warn!(
+            "PR_SET_NO_NEW_PRIVS failed ({}); continuing without this hardening",
+            err
+        );
+    } else {
+        tracing::debug!("PR_SET_NO_NEW_PRIVS=1 applied");
+    }
+
+    // ── RLIMIT_CORE = 0 ────────────────────────────────────────────────────
+    //
+    // Disables core dumps at the rlimit level. In combination with
+    // PR_SET_DUMPABLE=0, this provides a belt-and-suspenders guarantee that
+    // no core file will ever be written.
+    //
+    // Safety: setrlimit modifies resource limits for the calling process only.
+    let rlim_core = libc::rlimit {
+        rlim_cur: 0,
+        rlim_max: 0,
+    };
+    let result = unsafe { libc::setrlimit(libc::RLIMIT_CORE, &raw const rlim_core) };
+    if result != 0 {
+        let err = std::io::Error::last_os_error();
+        tracing::warn!(
+            "RLIMIT_CORE failed ({}); continuing without this hardening",
+            err
+        );
+    } else {
+        tracing::debug!("RLIMIT_CORE=0 applied");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_apply_process_hardening_does_not_panic() {
+        // This test exists to ensure the function can be called without
+        // panicking, even on platforms where hardening is a no-op.
+        apply_process_hardening();
+    }
+}
diff --git a/crates/tui/src/sandbox/seccomp.rs b/crates/tui/src/sandbox/seccomp.rs
new file mode 100644
index 00000000..b384ed8c
--- /dev/null
+++ b/crates/tui/src/sandbox/seccomp.rs
@@ -0,0 +1,405 @@
+//! Linux seccomp (Secure Computing) filter layer (#2182).
+//!
+//! Seccomp BPF (Berkeley Packet Filter) is a kernel facility that allows a
+//! process to restrict the system calls it (and its descendants) can make.
+//! This module applies a seccomp filter on top of Landlock to provide a
+//! second layer of defense — even if Landlock misbehaves or is configured
+//! too permissively, the seccomp filter blocks entire *classes* of dangerous
+//! syscalls like `ptrace`, `mount`, `kexec_load`, etc.
+//!
+//! # Architecture
+//!
+//! The filter is written as a raw BPF program (array of `sock_filter`
+//! instructions) and loaded via `prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER)`.
+//! This avoids any dependency on external crates like `libseccomp-sys` or
+//! `seccompiler` — we use only the `libc` crate already in the dependency
+//! tree.
+//!
+//! # Whitelisted syscalls
+//!
+//! The filter uses a whitelist approach: only syscalls that are known to be
+//! safe for a development/shell workload are allowed. Everything else is
+//! killed with `SECCOMP_RET_KILL_PROCESS`. The whitelist includes:
+//!
+//! - File I/O: read, write, open, openat, close, stat, fstat, lstat, newfstatat
+//! - Directory: getdents, getdents64, getcwd, chdir
+//! - Memory: mmap, mprotect, munmap, brk, mremap, madvise
+//! - Process: clone, clone3, fork, vfork, execve, execveat, exit, exit_group
+//! - IPC: pipe, pipe2, socket, socketpair, connect, bind, listen, accept, accept4
+//! - Synchronization: futex, nanosleep, clock_nanosleep
+//! - Signals: rt_sigaction, rt_sigprocmask, rt_sigreturn, kill, tkill, tgkill
+//! - Resource: getrlimit, setrlimit, prlimit64, getrusage
+//! - Time: clock_gettime, gettimeofday, time
+//! - Misc: getpid, gettid, getuid, geteuid, getgid, getegid, uname, arch_prctl
+//!
+//! # Explicitly denied
+//!
+//! - ptrace (process hijacking)
+//! - mount, umount2 (filesystem manipulation)
+//! - kexec_load, kexec_file_load (kernel execution)
+//! - init_module, finit_module, delete_module (kernel module loading)
+//! - bpf (loading BPF programs — would bypass seccomp!)
+//! - reboot
+//! - swapon, swapoff
+//! - pivot_root
+//! - setuid, setgid, setreuid, setregid, setresuid, setresgid
+//! - personality
+//!
+//! # Safety
+//!
+//! Once the seccomp filter is installed, it is **irreversible** — even
+//! `prctl(PR_SET_SECCOMP, ...)` is denied. This is by design.
+
+/// Check if seccomp is available on this system.
+///
+/// Returns true if `/proc/sys/kernel/seccomp/actions_avail` exists and
+/// contains "kill_process", indicating the kernel supports seccomp BPF.
+#[cfg(target_os = "linux")]
+pub fn is_available() -> bool {
+    std::path::Path::new("/proc/sys/kernel/seccomp/actions_avail").exists()
+}
+
+#[cfg(not(target_os = "linux"))]
+pub fn is_available() -> bool {
+    false
+}
+
+/// Detect if a failure was caused by seccomp denial.
+///
+/// Seccomp kills the process with SIGSYS (or the thread with SECCOMP_RET_KILL_THREAD),
+/// and the exit code is typically SIGSYS (31) or the process may be killed with
+/// "Bad system call" on stderr.
+///
+/// Additionally, seccomp violations may produce EPERM for filtered syscalls
+/// if using SECCOMP_RET_ERRNO.
+#[cfg(target_os = "linux")]
+pub fn detect_denial(exit_code: i32, stderr: &str) -> bool {
+    // SIGSYS = 31
+    if exit_code == 31 {
+        return true;
+    }
+    // Check for seccomp denial patterns in stderr
+    stderr.contains("Bad system call")
+        || stderr.contains("bad system call")
+        || stderr.contains("SIGSYS")
+        || stderr.contains("seccomp")
+        || stderr.contains("invalid argument") && exit_code == 159
+    // 159 = 128 + 31 (died from SIGSYS with core dump disabled)
+}
+
+#[cfg(not(target_os = "linux"))]
+pub fn detect_denial(_exit_code: i32, _stderr: &str) -> bool {
+    false
+}
+
+/// Apply the seccomp filter to the calling thread.
+///
+/// This installs a BPF program that whitelists safe syscalls and kills the
+/// process on any disallowed syscall.
+///
+/// # Errors
+///
+/// Returns an error if the prctl call fails (e.g., seccomp already enabled
+/// or kernel too old).
+#[cfg(target_os = "linux")]
+pub fn apply_seccomp_filter() -> std::io::Result<()> {
+    // ── Build the BPF filter program ─────────────────────────────────────
+    //
+    // BPF for seccomp works as follows:
+    // 1. Load the architecture (4 bytes at offset 4 in seccomp_data)
+    // 2. Validate architecture matches AUDIT_ARCH_X86_64 (0xC000003E)
+    // 3. Load the syscall number (4 bytes at offset 0)
+    // 4. Compare against whitelist, return ALLOW on match
+    // 5. Return KILL on no match
+    //
+    // The filter uses a linear search over the whitelist. While not optimal,
+    // it's simple, auditable, and has no external dependencies. The BPF
+    // program is at most a few hundred instructions, which is well within
+    // the kernel's 4096-instruction limit.
+
+    #[repr(C)]
+    struct sock_filter {
+        code: u16,
+        jt: u8,
+        jf: u8,
+        k: u32,
+    }
+
+    const BPF_LD: u16 = 0x00;
+    const BPF_JMP: u16 = 0x05;
+    const BPF_RET: u16 = 0x06;
+
+    const BPF_W: u16 = 0x00;
+    const BPF_ABS: u16 = 0x20;
+
+    const BPF_JEQ: u16 = 0x10;
+    const BPF_JGE: u16 = 0x30;
+    const BPF_JA: u16 = 0x00;
+
+    const SECCOMP_RET_KILL_PROCESS: u32 = 0x8000_0000;
+    const SECCOMP_RET_ALLOW: u32 = 0x7FFF_0000;
+
+    // Audit arch for x86_64
+    const AUDIT_ARCH_X86_64: u32 = 0xC000_003E;
+
+    // Helper to build a BPF instruction compactly.
+    // Pattern from openai/codex codex-rs/codex-sandbox/src/linux/seccomp.rs; reimplemented.
+
+    // Whitelist of safe syscall numbers (x86_64).
+    // These are the syscalls most commonly used by shell commands, compilers,
+    // and developer tools. Any syscall NOT on this list causes immediate SIGSYS.
+    let allowed_syscalls: &[u32] = &[
+        0,   // read
+        1,   // write
+        2,   // open
+        3,   // close
+        4,   // stat
+        5,   // fstat
+        6,   // lstat
+        7,   // poll
+        8,   // lseek
+        9,   // mmap
+        10,  // mprotect
+        11,  // munmap
+        12,  // brk
+        13,  // rt_sigaction
+        14,  // rt_sigprocmask
+        15,  // rt_sigreturn
+        16,  // ioctl
+        17,  // pread64
+        18,  // pwrite64
+        19,  // readv
+        20,  // writev
+        21,  // access
+        22,  // pipe
+        23,  // select
+        24,  // sched_yield
+        25,  // mremap
+        27,  // mincore
+        28,  // madvise
+        29,  // shmget
+        30,  // shmat
+        32,  // dup
+        33,  // dup2
+        35,  // nanosleep
+        39,  // getpid
+        41,  // socket
+        42,  // connect
+        43,  // accept
+        44,  // sendto
+        45,  // recvfrom
+        46,  // sendmsg
+        47,  // recvmsg
+        48,  // shutdown
+        49,  // bind
+        50,  // listen
+        51,  // getsockname
+        52,  // getpeername
+        53,  // socketpair
+        54,  // setsockopt
+        55,  // getsockopt
+        56,  // clone
+        57,  // fork
+        58,  // vfork
+        59,  // execve
+        60,  // exit
+        61,  // wait4
+        62,  // kill
+        63,  // uname
+        72,  // fcntl
+        73,  // flock
+        74,  // fsync
+        75,  // fdatasync
+        76,  // truncate
+        77,  // ftruncate
+        78,  // getdents
+        79,  // getcwd
+        80,  // chdir
+        81,  // fchdir
+        82,  // rename
+        83,  // mkdir
+        84,  // rmdir
+        85,  // creat
+        86,  // link
+        87,  // unlink
+        88,  // symlink
+        89,  // readlink
+        90,  // chmod
+        91,  // fchmod
+        92,  // chown
+        93,  // fchown
+        94,  // lchown
+        95,  // umask
+        96,  // gettimeofday
+        97,  // getrlimit
+        98,  // getrusage
+        99,  // sysinfo
+        100, // times
+        102, // getuid
+        104, // getgid
+        107, // geteuid
+        108, // getegid
+        110, // getppid
+        111, // getpgrp
+        112, // setsid
+        116, // syslog
+        131, // sigaltstack
+        137, // statfs
+        138, // fstatfs
+        157, // prctl
+        158, // arch_prctl
+        186, // gettid
+        201, // time
+        202, // futex
+        204, // sched_getaffinity
+        217, // getdents64
+        218, // set_tid_address
+        228, // clock_gettime
+        230, // clock_nanosleep
+        231, // exit_group
+        232, // epoll_wait
+        233, // epoll_ctl
+        234, // tgkill
+        235, // utimes
+        257, // openat
+        262, // newfstatat
+        273, // set_robust_list
+        281, // epoll_pwait
+        291, // epoll_create1
+        292, // dup3
+        293, // pipe2
+        302, // prlimit64
+        318, // getrandom
+        332, // statx
+        334, // rseq
+        435, // clone3
+    ];
+
+    // Build the BPF program.
+    let mut filter = vec![
+        // Instruction 0: load architecture from seccomp_data.arch
+        sock_filter {
+            code: BPF_LD | BPF_W | BPF_ABS,
+            jt: 0,
+            jf: 0,
+            k: 4, // offset of arch in seccomp_data
+        },
+        // Instruction 1: compare with AUDIT_ARCH_X86_64
+        // If match, jump to next instruction; if not, kill process
+        sock_filter {
+            code: BPF_JMP | BPF_JEQ,
+            jt: 0,
+            jf: 1, // jump 1 forward (to KILL) if arch doesn't match
+            k: AUDIT_ARCH_X86_64,
+        },
+        // Instruction 2: KILL (wrong architecture)
+        sock_filter {
+            code: BPF_RET,
+            jt: 0,
+            jf: 0,
+            k: SECCOMP_RET_KILL_PROCESS,
+        },
+        // Instruction 3: load syscall number from seccomp_data.nr
+        sock_filter {
+            code: BPF_LD | BPF_W | BPF_ABS,
+            jt: 0,
+            jf: 0,
+            k: 0, // offset of nr in seccomp_data
+        },
+    ];
+
+    // For each allowed syscall, add a compare+jump to ALLOW.
+    // We use a linear scan for simplicity: each JEQ instruction jumps
+    // forward over the remaining checks + KILL to reach ALLOW.
+    for &syscall in allowed_syscalls {
+        let remaining = (allowed_syscalls.len() as u8).saturating_sub(
+            allowed_syscalls
+                .iter()
+                .position(|&s| s == syscall)
+                .unwrap_or(0) as u8,
+        );
+        // If syscall == this one, jump to allow_target; otherwise fall through
+        filter.push(sock_filter {
+            code: BPF_JMP | BPF_JEQ,
+            jt: remaining, // jump forward to ALLOW
+            jf: 0,         // fall through to next check
+            k: syscall,
+        });
+    }
+
+    // Instruction N: KILL PROCESS for any unmatched syscall
+    filter.push(sock_filter {
+        code: BPF_RET,
+        jt: 0,
+        jf: 0,
+        k: SECCOMP_RET_KILL_PROCESS,
+    });
+
+    // Instruction N+1: ALLOW
+    filter.push(sock_filter {
+        code: BPF_RET,
+        jt: 0,
+        jf: 0,
+        k: SECCOMP_RET_ALLOW,
+    });
+
+    // ── Load the filter into the kernel ───────────────────────────────────
+
+    #[repr(C)]
+    struct sock_fprog {
+        len: u16,
+        filter: *const sock_filter,
+    }
+
+    let prog = sock_fprog {
+        len: filter.len() as u16,
+        filter: filter.as_ptr(),
+    };
+
+    // Safety: prctl with PR_SET_SECCOMP installs a seccomp BPF filter.
+    // The filter is a valid array of sock_filter instructions that lives
+    // for the duration of the prctl call.
+    let result = unsafe {
+        libc::prctl(
+            libc::PR_SET_SECCOMP,
+            libc::SECCOMP_MODE_FILTER,
+            &raw const prog,
+            0i64,
+            0i64,
+        )
+    };
+
+    if result != 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_is_available_does_not_panic() {
+        let _ = is_available();
+    }
+
+    #[test]
+    #[cfg(target_os = "linux")]
+    fn test_detect_denial() {
+        assert!(detect_denial(31, ""));
+        assert!(detect_denial(1, "Bad system call"));
+        assert!(detect_denial(1, "SIGSYS"));
+        assert!(!detect_denial(0, "Success"));
+        assert!(!detect_denial(1, "File not found"));
+    }
+
+    #[test]
+    fn test_detect_denial_non_linux() {
+        #[cfg(not(target_os = "linux"))]
+        {
+            assert!(!detect_denial(31, "Bad system call"));
+        }
+    }
+}
diff --git a/crates/tui/src/session_failure_classifier.rs b/crates/tui/src/session_failure_classifier.rs
new file mode 100644
index 00000000..a88b87c9
--- /dev/null
+++ b/crates/tui/src/session_failure_classifier.rs
@@ -0,0 +1,513 @@
+//! Redacted session/tool failure classification.
+//!
+//! This module is deliberately pure: callers provide already-parsed,
+//! caller-constructed records and receive aggregate counts plus redacted
+//! source handles. It does not read session files or copy raw tool output.
+
+use std::collections::BTreeMap;
+
+use serde::Serialize;
+
+/// Environment/tool failure shapes that should be separated from model-quality
+/// failures during triage.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FailureCategory {
+    CommandExit,
+    Network,
+    SandboxApproval,
+    MissingDependencyPath,
+    Timeout,
+    UnclosedTurn,
+    Unknown,
+}
+
+impl FailureCategory {
+    #[must_use]
+    pub fn is_environment_suspect(self) -> bool {
+        !matches!(self, Self::Unknown)
+    }
+}
+
+/// One caller-supplied synthetic session record.
+#[derive(Debug, Clone)]
+pub struct SessionFailureRecord<'a> {
+    /// Untrusted source locator. The classifier hashes it before output.
+    pub source_hint: &'a str,
+    /// Optional timestamp to preserve enough local evidence metadata for
+    /// maintainers who have access to the private source.
+    pub timestamp: Option<&'a str>,
+    pub event: SessionFailureEvent<'a>,
+}
+
+/// Synthetic event shape used by the classifier.
+#[derive(Debug, Clone)]
+pub enum SessionFailureEvent<'a> {
+    TurnStarted { turn_id: &'a str },
+    TurnCompleted { turn_id: &'a str },
+    Tool(ToolFailureRecord<'a>),
+}
+
+/// Caller-supplied tool record. Text fields are classification inputs only and
+/// are never copied into [`FailureEvidence`].
+#[derive(Debug, Clone, Default)]
+pub struct ToolFailureRecord<'a> {
+    pub tool_name: &'a str,
+    pub success: Option<bool>,
+    pub exit_code: Option<i32>,
+    pub timed_out: bool,
+    pub sandbox_denied: bool,
+    pub approval_denied: bool,
+    pub diagnostic: Option<&'a str>,
+    pub output_excerpt: Option<&'a str>,
+}
+
+/// Redacted per-failure locator emitted by default.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct FailureEvidence {
+    pub category: FailureCategory,
+    pub source_handle: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub timestamp: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub exit_code: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_handle: Option<String>,
+}
+
+/// Aggregate classifier output safe for status, handoff, or bug-report
+/// preflight surfaces.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize)]
+pub struct FailureSummary {
+    pub counts: BTreeMap<FailureCategory, usize>,
+    pub evidence: Vec<FailureEvidence>,
+}
+
+impl FailureSummary {
+    #[must_use]
+    pub fn count_for(&self, category: FailureCategory) -> usize {
+        self.counts.get(&category).copied().unwrap_or(0)
+    }
+
+    #[must_use]
+    pub fn environment_suspect_count(&self) -> usize {
+        self.evidence
+            .iter()
+            .filter(|item| item.category.is_environment_suspect())
+            .count()
+    }
+
+    fn push(&mut self, evidence: FailureEvidence) {
+        *self.counts.entry(evidence.category).or_insert(0) += 1;
+        self.evidence.push(evidence);
+    }
+}
+
+#[derive(Debug, Clone)]
+struct OpenTurn {
+    source_handle: String,
+    timestamp: Option<String>,
+    turn_handle: String,
+}
+
+/// Classify a caller-supplied slice of synthetic records.
+#[must_use]
+pub fn summarize_records(records: &[SessionFailureRecord<'_>]) -> FailureSummary {
+    let mut summary = FailureSummary::default();
+    let mut open_turns: BTreeMap<String, OpenTurn> = BTreeMap::new();
+
+    for record in records {
+        let source_handle = redacted_handle("src", record.source_hint);
+        let timestamp = record.timestamp.map(ToOwned::to_owned);
+
+        match &record.event {
+            SessionFailureEvent::TurnStarted { turn_id } => {
+                open_turns.insert(
+                    (*turn_id).to_owned(),
+                    OpenTurn {
+                        source_handle,
+                        timestamp,
+                        turn_handle: redacted_handle("turn", turn_id),
+                    },
+                );
+            }
+            SessionFailureEvent::TurnCompleted { turn_id } => {
+                open_turns.remove(*turn_id);
+            }
+            SessionFailureEvent::Tool(tool) => {
+                if let Some(category) = classify_tool_record(tool) {
+                    summary.push(FailureEvidence {
+                        category,
+                        source_handle,
+                        timestamp,
+                        tool_name: Some(sanitize_tool_name(tool.tool_name)),
+                        exit_code: tool.exit_code.filter(|code| *code != 0),
+                        turn_handle: None,
+                    });
+                }
+            }
+        }
+    }
+
+    for turn in open_turns.into_values() {
+        summary.push(FailureEvidence {
+            category: FailureCategory::UnclosedTurn,
+            source_handle: turn.source_handle,
+            timestamp: turn.timestamp,
+            tool_name: None,
+            exit_code: None,
+            turn_handle: Some(turn.turn_handle),
+        });
+    }
+
+    summary
+}
+
+/// Classify one tool record. Returns `None` for successful/no-signal records.
+#[must_use]
+pub fn classify_tool_record(record: &ToolFailureRecord<'_>) -> Option<FailureCategory> {
+    let failed = record.success == Some(false)
+        || record.exit_code.is_some_and(|code| code != 0)
+        || record.timed_out
+        || record.sandbox_denied
+        || record.approval_denied
+        || record.diagnostic.is_some()
+        || record.output_excerpt.is_some();
+
+    if !failed {
+        return None;
+    }
+
+    if record.timed_out || record.matches_text(timeout_signal) {
+        return Some(FailureCategory::Timeout);
+    }
+    if record.sandbox_denied
+        || record.approval_denied
+        || record.matches_text(sandbox_or_approval_signal)
+    {
+        return Some(FailureCategory::SandboxApproval);
+    }
+    if record.matches_text(network_signal) {
+        return Some(FailureCategory::Network);
+    }
+    if record.matches_text(missing_dependency_or_path_signal) {
+        return Some(FailureCategory::MissingDependencyPath);
+    }
+    if record.exit_code.is_some_and(|code| code != 0) {
+        return Some(FailureCategory::CommandExit);
+    }
+
+    Some(FailureCategory::Unknown)
+}
+
+impl ToolFailureRecord<'_> {
+    fn matches_text(&self, predicate: fn(&str) -> bool) -> bool {
+        self.diagnostic.is_some_and(predicate) || self.output_excerpt.is_some_and(predicate)
+    }
+}
+
+fn timeout_signal(text: &str) -> bool {
+    let lower = text.to_ascii_lowercase();
+    lower.contains("timed out")
+        || lower.contains("timeout")
+        || lower.contains("deadline exceeded")
+        || lower.contains("operation took too long")
+}
+
+fn sandbox_or_approval_signal(text: &str) -> bool {
+    let lower = text.to_ascii_lowercase();
+    lower.contains("sandbox")
+        || lower.contains("seatbelt")
+        || lower.contains("landlock")
+        || lower.contains("seccomp")
+        || lower.contains("approval")
+        || lower.contains("denied by user")
+        || lower.contains("user denied")
+        || lower.contains("permission denied")
+        || lower.contains("operation not permitted")
+        || lower.contains("blocked by policy")
+}
+
+fn network_signal(text: &str) -> bool {
+    let lower = text.to_ascii_lowercase();
+    lower.contains("network")
+        || lower.contains("dns")
+        || lower.contains("could not resolve")
+        || lower.contains("name or service not known")
+        || lower.contains("temporary failure in name resolution")
+        || lower.contains("connection refused")
+        || lower.contains("connection reset")
+        || lower.contains("connection closed")
+        || lower.contains("failed to connect")
+        || lower.contains("tls")
+        || lower.contains("ssl")
+        || lower.contains("http 502")
+        || lower.contains("http 503")
+        || lower.contains("http 504")
+        || lower.contains(" 502 ")
+        || lower.contains(" 503 ")
+        || lower.contains(" 504 ")
+        || lower.starts_with("502 ")
+        || lower.starts_with("503 ")
+        || lower.starts_with("504 ")
+        || lower.ends_with(" 502")
+        || lower.ends_with(" 503")
+        || lower.ends_with(" 504")
+        || matches!(lower.as_str(), "502" | "503" | "504")
+        || lower.contains("curl: (6)")
+        || lower.contains("curl: (7)")
+        || lower.contains("curl: (35)")
+        || lower.contains("curl: (56)")
+}
+
+fn missing_dependency_or_path_signal(text: &str) -> bool {
+    let lower = text.to_ascii_lowercase();
+    lower.contains("command not found")
+        || lower.contains("no such file or directory")
+        || lower.contains("enoent")
+        || lower.contains("not recognized as an internal or external command")
+        || lower.contains("cannot find the path")
+        || lower.contains("failed to locate tool")
+        || lower.contains("module not found")
+        || lower.contains("modulenotfounderror")
+        || lower.contains("no module named")
+        || lower.contains("missing binary")
+        || lower.contains("missing dependency")
+}
+
+fn sanitize_tool_name(raw: &str) -> String {
+    let sanitized: String = raw
+        .chars()
+        .filter(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-' | '.'))
+        .take(64)
+        .collect();
+    if sanitized.is_empty() {
+        "tool".to_string()
+    } else {
+        sanitized
+    }
+}
+
+fn redacted_handle(prefix: &str, raw: &str) -> String {
+    if raw.trim().is_empty() {
+        return format!("{prefix}_unspecified");
+    }
+    format!("{prefix}_{:016x}", stable_hash(raw))
+}
+
+fn stable_hash(raw: &str) -> u64 {
+    let mut hash = 0xcbf2_9ce4_8422_2325u64;
+    for byte in raw.as_bytes() {
+        hash ^= u64::from(*byte);
+        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    hash
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn tool<'a>(
+        source_hint: &'a str,
+        tool_name: &'a str,
+        exit_code: Option<i32>,
+        diagnostic: &'a str,
+    ) -> SessionFailureRecord<'a> {
+        SessionFailureRecord {
+            source_hint,
+            timestamp: Some("2026-05-24T21:00:00Z"),
+            event: SessionFailureEvent::Tool(ToolFailureRecord {
+                tool_name,
+                success: Some(false),
+                exit_code,
+                diagnostic: Some(diagnostic),
+                ..ToolFailureRecord::default()
+            }),
+        }
+    }
+
+    #[test]
+    fn classifies_synthetic_environment_and_tool_failure_shapes() {
+        let records = vec![
+            tool(
+                "/Users/hunter/private/session-a.jsonl",
+                "exec_shell",
+                Some(101),
+                "cargo test failed",
+            ),
+            tool(
+                "/Users/hunter/private/session-b.jsonl",
+                "web_run",
+                Some(6),
+                "curl: (6) Could not resolve host: example.invalid",
+            ),
+            SessionFailureRecord {
+                source_hint: "/Users/hunter/private/session-c.jsonl",
+                timestamp: Some("2026-05-24T21:01:00Z"),
+                event: SessionFailureEvent::Tool(ToolFailureRecord {
+                    tool_name: "exec_shell",
+                    success: Some(false),
+                    exit_code: Some(1),
+                    sandbox_denied: true,
+                    diagnostic: Some("sandbox-exec blocked file-write"),
+                    ..ToolFailureRecord::default()
+                }),
+            },
+            tool(
+                "/Users/hunter/private/session-d.jsonl",
+                "exec_shell",
+                Some(127),
+                "zsh: command not found: cargo-nextest",
+            ),
+            SessionFailureRecord {
+                source_hint: "/Users/hunter/private/session-e.jsonl",
+                timestamp: Some("2026-05-24T21:02:00Z"),
+                event: SessionFailureEvent::Tool(ToolFailureRecord {
+                    tool_name: "fetch_url",
+                    success: Some(false),
+                    timed_out: true,
+                    diagnostic: Some("operation timed out after 60s"),
+                    ..ToolFailureRecord::default()
+                }),
+            },
+            SessionFailureRecord {
+                source_hint: "/Users/hunter/private/session-f.jsonl",
+                timestamp: Some("2026-05-24T21:03:00Z"),
+                event: SessionFailureEvent::TurnStarted {
+                    turn_id: "turn-private-123",
+                },
+            },
+        ];
+
+        let summary = summarize_records(&records);
+
+        assert_eq!(summary.count_for(FailureCategory::CommandExit), 1);
+        assert_eq!(summary.count_for(FailureCategory::Network), 1);
+        assert_eq!(summary.count_for(FailureCategory::SandboxApproval), 1);
+        assert_eq!(summary.count_for(FailureCategory::MissingDependencyPath), 1);
+        assert_eq!(summary.count_for(FailureCategory::Timeout), 1);
+        assert_eq!(summary.count_for(FailureCategory::UnclosedTurn), 1);
+        assert_eq!(summary.environment_suspect_count(), 6);
+    }
+
+    #[test]
+    fn specific_environment_signals_beat_generic_nonzero_exit() {
+        let network = ToolFailureRecord {
+            tool_name: "exec_shell",
+            success: Some(false),
+            exit_code: Some(1),
+            diagnostic: Some("DNS lookup failed"),
+            ..ToolFailureRecord::default()
+        };
+        let missing = ToolFailureRecord {
+            tool_name: "exec_shell",
+            success: Some(false),
+            exit_code: Some(127),
+            diagnostic: Some("No such file or directory"),
+            ..ToolFailureRecord::default()
+        };
+        let approval = ToolFailureRecord {
+            tool_name: "edit_file",
+            success: Some(false),
+            exit_code: Some(1),
+            approval_denied: true,
+            diagnostic: Some("denied by user"),
+            ..ToolFailureRecord::default()
+        };
+        let timeout = ToolFailureRecord {
+            tool_name: "web_run",
+            success: Some(false),
+            exit_code: Some(124),
+            diagnostic: Some("deadline exceeded"),
+            ..ToolFailureRecord::default()
+        };
+
+        assert_eq!(
+            classify_tool_record(&network),
+            Some(FailureCategory::Network)
+        );
+        assert_eq!(
+            classify_tool_record(&missing),
+            Some(FailureCategory::MissingDependencyPath)
+        );
+        assert_eq!(
+            classify_tool_record(&approval),
+            Some(FailureCategory::SandboxApproval)
+        );
+        assert_eq!(
+            classify_tool_record(&timeout),
+            Some(FailureCategory::Timeout)
+        );
+    }
+
+    #[test]
+    fn successful_records_and_closed_turns_do_not_emit_failures() {
+        let records = vec![
+            SessionFailureRecord {
+                source_hint: "session-ok",
+                timestamp: None,
+                event: SessionFailureEvent::TurnStarted { turn_id: "turn-1" },
+            },
+            SessionFailureRecord {
+                source_hint: "session-ok",
+                timestamp: None,
+                event: SessionFailureEvent::Tool(ToolFailureRecord {
+                    tool_name: "exec_shell",
+                    success: Some(true),
+                    exit_code: Some(0),
+                    diagnostic: None,
+                    ..ToolFailureRecord::default()
+                }),
+            },
+            SessionFailureRecord {
+                source_hint: "session-ok",
+                timestamp: None,
+                event: SessionFailureEvent::TurnCompleted { turn_id: "turn-1" },
+            },
+        ];
+
+        let summary = summarize_records(&records);
+
+        assert!(summary.counts.is_empty());
+        assert!(summary.evidence.is_empty());
+    }
+
+    #[test]
+    fn summary_uses_redacted_handles_and_does_not_copy_raw_content() {
+        let records = vec![
+            SessionFailureRecord {
+                source_hint: "/Users/hunter/private/session-secret.jsonl",
+                timestamp: Some("2026-05-24T21:04:00Z"),
+                event: SessionFailureEvent::Tool(ToolFailureRecord {
+                    tool_name: "exec shell with spaces",
+                    success: Some(false),
+                    exit_code: Some(1),
+                    diagnostic: Some("fatal output contained sk-test-secret and /private/path"),
+                    output_excerpt: Some("raw transcript text that must stay private"),
+                    ..ToolFailureRecord::default()
+                }),
+            },
+            SessionFailureRecord {
+                source_hint: "/Users/hunter/private/session-secret.jsonl",
+                timestamp: Some("2026-05-24T21:05:00Z"),
+                event: SessionFailureEvent::TurnStarted {
+                    turn_id: "private-turn-id",
+                },
+            },
+        ];
+
+        let encoded = serde_json::to_string(&summarize_records(&records)).unwrap();
+
+        assert!(!encoded.contains("/Users/hunter"));
+        assert!(!encoded.contains("session-secret"));
+        assert!(!encoded.contains("sk-test-secret"));
+        assert!(!encoded.contains("raw transcript text"));
+        assert!(!encoded.contains("private-turn-id"));
+        assert!(encoded.contains("src_"));
+        assert!(encoded.contains("turn_"));
+        assert!(encoded.contains("execshellwithspaces"));
+    }
+}
diff --git a/crates/tui/src/session_manager.rs b/crates/tui/src/session_manager.rs
index c5a69193..e1ac5e25 100644
--- a/crates/tui/src/session_manager.rs
+++ b/crates/tui/src/session_manager.rs
@@ -132,6 +132,11 @@ pub struct SessionMetadata {
     /// current saved sessions are linear JSON files, not per-entry trees.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub forked_from_message_count: Option<usize>,
+    /// Cumulative turn duration in seconds (sum of completed turn elapsed
+    /// times). Persisted so the footer "worked" chip survives restarts
+    /// (#2038).
+    #[serde(default)]
+    pub cumulative_turn_secs: u64,
 }
 
 /// Cost and high-water-mark fields persisted with each session.
@@ -256,7 +261,7 @@ impl SessionManager {
     pub fn save_session(&self, session: &SavedSession) -> std::io::Result<PathBuf> {
         let path = self.validated_session_path(&session.metadata.id)?;
 
-        let content = serde_json::to_string_pretty(session)
+        let content = serde_json::to_string_pretty(&session)
             .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
 
         // Atomic write via write_atomic (NamedTempFile + fsync + persist)
@@ -273,7 +278,7 @@ impl SessionManager {
         let checkpoints = self.sessions_dir.join("checkpoints");
         fs::create_dir_all(&checkpoints)?;
         let path = checkpoints.join("latest.json");
-        let content = serde_json::to_string_pretty(session)
+        let content = serde_json::to_string_pretty(&session)
             .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
         write_atomic(&path, content.as_bytes())?;
         Ok(path)
@@ -723,6 +728,7 @@ pub fn create_saved_session_with_id_and_mode(
             cost: SessionCostSnapshot::default(),
             parent_session_id: None,
             forked_from_message_count: None,
+            cumulative_turn_secs: 0,
         },
         messages: capped_messages,
         system_prompt: merge_truncation_note(
@@ -1045,6 +1051,7 @@ mod tests {
                 cost: SessionCostSnapshot::default(),
                 parent_session_id: None,
                 forked_from_message_count: None,
+                cumulative_turn_secs: 0,
             },
             system_prompt: None,
             context_references: Vec::new(),
@@ -1075,6 +1082,7 @@ mod tests {
                 cost: SessionCostSnapshot::default(),
                 parent_session_id: None,
                 forked_from_message_count: None,
+                cumulative_turn_secs: 0,
             },
             system_prompt: None,
             context_references: Vec::new(),
@@ -1111,6 +1119,118 @@ mod tests {
         assert_eq!(loaded.messages.len(), 2);
     }
 
+    #[test]
+    fn save_session_preserves_large_tool_outputs_for_cache_fidelity() {
+        let tmp = tempdir().expect("tempdir");
+        let manager = SessionManager::new(tmp.path().join("sessions")).expect("new");
+        let raw = "RAW_SESSION_SENTINEL\n".repeat(2_000);
+        let messages = vec![
+            Message {
+                role: "assistant".to_string(),
+                content: vec![ContentBlock::ToolUse {
+                    id: "call-big".to_string(),
+                    name: "exec_shell".to_string(),
+                    input: serde_json::json!({"command": "cargo test -p codewhale-tui"}),
+                    caller: None,
+                }],
+            },
+            Message {
+                role: "user".to_string(),
+                content: vec![ContentBlock::ToolResult {
+                    tool_use_id: "call-big".to_string(),
+                    content: raw.clone(),
+                    is_error: None,
+                    content_blocks: None,
+                }],
+            },
+        ];
+        let mut session = create_saved_session(&messages, "test-model", tmp.path(), 100, None);
+        session.artifacts.push(crate::artifacts::ArtifactRecord {
+            id: "art_call-big".to_string(),
+            kind: crate::artifacts::ArtifactKind::ToolOutput,
+            session_id: session.metadata.id.clone(),
+            tool_call_id: "call-big".to_string(),
+            tool_name: "exec_shell".to_string(),
+            created_at: Utc::now(),
+            byte_size: raw.len() as u64,
+            preview: "checking crate ... error[E0425]".to_string(),
+            storage_path: PathBuf::from("artifacts/art_call-big.txt"),
+        });
+
+        let path = manager.save_session(&session).expect("save");
+        let persisted_json = fs::read_to_string(path).expect("read persisted session");
+        // Raw output is preserved in-session so resume can hit the LLM cache.
+        assert!(persisted_json.contains("RAW_SESSION_SENTINEL"));
+
+        let loaded = manager.load_session(&session.metadata.id).expect("load");
+        let ContentBlock::ToolResult { content, .. } = &loaded.messages[1].content[0] else {
+            panic!("expected loaded tool result");
+        };
+        // Loaded session retains the original output for cache fidelity.
+        assert!(content.contains("RAW_SESSION_SENTINEL"));
+        assert!(!content.contains("[TOOL_OUTPUT_RECEIPT]"));
+    }
+
+    #[test]
+    fn load_session_preserves_legacy_large_tool_outputs_for_cache_fidelity() {
+        let tmp = tempdir().expect("tempdir");
+        let manager = SessionManager::new(tmp.path().join("sessions")).expect("new");
+        let raw = "RAW_LEGACY_RESUME_SENTINEL\n".repeat(2_000);
+        let messages = vec![
+            Message {
+                role: "assistant".to_string(),
+                content: vec![ContentBlock::ToolUse {
+                    id: "call-legacy".to_string(),
+                    name: "exec_shell".to_string(),
+                    input: serde_json::json!({"command": "cargo check"}),
+                    caller: None,
+                }],
+            },
+            Message {
+                role: "user".to_string(),
+                content: vec![ContentBlock::ToolResult {
+                    tool_use_id: "call-legacy".to_string(),
+                    content: raw.clone(),
+                    is_error: None,
+                    content_blocks: None,
+                }],
+            },
+        ];
+        let mut session = create_saved_session(&messages, "test-model", tmp.path(), 100, None);
+        session.artifacts.push(crate::artifacts::ArtifactRecord {
+            id: "art_call-legacy".to_string(),
+            kind: crate::artifacts::ArtifactKind::ToolOutput,
+            session_id: session.metadata.id.clone(),
+            tool_call_id: "call-legacy".to_string(),
+            tool_name: "exec_shell".to_string(),
+            created_at: Utc::now(),
+            byte_size: raw.len() as u64,
+            preview: "cargo check output".to_string(),
+            storage_path: PathBuf::from("artifacts/art_call-legacy.txt"),
+        });
+        let path = manager
+            .validated_session_path(&session.metadata.id)
+            .expect("path");
+        fs::write(
+            &path,
+            serde_json::to_string_pretty(&session).expect("serialize legacy session"),
+        )
+        .expect("write legacy raw session");
+        assert!(
+            fs::read_to_string(&path)
+                .expect("read legacy raw")
+                .contains("RAW_LEGACY_RESUME_SENTINEL")
+        );
+
+        let loaded = manager.load_session(&session.metadata.id).expect("load");
+        let ContentBlock::ToolResult { content, .. } = &loaded.messages[1].content[0] else {
+            panic!("expected loaded tool result");
+        };
+        // Loaded session preserves original output so resume can hit the LLM cache.
+        assert!(content.contains("RAW_LEGACY_RESUME_SENTINEL"));
+        assert!(!content.contains("[TOOL_OUTPUT_RECEIPT]"));
+    }
+
     #[test]
     fn test_list_sessions() {
         let tmp = tempdir().expect("tempdir");
diff --git a/crates/tui/src/settings.rs b/crates/tui/src/settings.rs
index d3401071..f4520af8 100644
--- a/crates/tui/src/settings.rs
+++ b/crates/tui/src/settings.rs
@@ -109,6 +109,10 @@ impl TuiPrefs {
 
         let home = dirs::home_dir()
             .context("Failed to resolve home directory: cannot determine tui.toml path.")?;
+        let primary = home.join(".codewhale").join("tui.toml");
+        if primary.exists() {
+            return Ok(primary);
+        }
         Ok(home.join(".deepseek").join("tui.toml"))
     }
 
@@ -273,11 +277,6 @@ pub struct Settings {
     /// `binary_unavailable` response with an install hint, matching the
     /// pre-v0.8.32 behavior.
     pub prefer_external_pdftotext: bool,
-    /// Optional command that records/transcribes voice input and writes the
-    /// final UTF-8 transcript to stdout. Triggered by the command palette.
-    pub voice_input_command: Option<String>,
-    /// Timeout for the configured voice input command, in seconds.
-    pub voice_input_timeout_secs: u64,
 }
 
 impl Default for Settings {
@@ -320,8 +319,6 @@ impl Default for Settings {
             status_indicator: "whale".to_string(),
             synchronized_output: "auto".to_string(),
             prefer_external_pdftotext: false,
-            voice_input_command: None,
-            voice_input_timeout_secs: crate::tui::voice_input::default_timeout_secs(),
         }
     }
 }
@@ -370,11 +367,6 @@ impl Settings {
                 .to_string();
             s.background_color = normalize_optional_background_color(s.background_color.as_deref());
             s.theme = normalize_settings_theme(&s.theme).to_string();
-            let voice_input_command =
-                normalize_optional_voice_input_command(s.voice_input_command.as_deref());
-            s.voice_input_command = voice_input_command;
-            s.voice_input_timeout_secs =
-                crate::tui::voice_input::clamp_timeout_secs(s.voice_input_timeout_secs);
             s.default_model = s.default_model.as_deref().and_then(normalize_default_model);
             s.reasoning_effort = s
                 .reasoning_effort
@@ -396,15 +388,6 @@ impl Settings {
             self.low_motion = true;
             self.fancy_animations = false;
         }
-        if let Ok(value) = std::env::var("DEEPSEEK_VOICE_INPUT_COMMAND") {
-            self.voice_input_command = normalize_optional_voice_input_command(Some(&value));
-        }
-        if let Ok(value) = std::env::var("DEEPSEEK_VOICE_INPUT_TIMEOUT_SECS")
-            && let Ok(timeout_secs) = value.trim().parse::<u64>()
-        {
-            self.voice_input_timeout_secs =
-                crate::tui::voice_input::clamp_timeout_secs(timeout_secs);
-        }
         // VS Code (TERM_PROGRAM=vscode, #1356), Ghostty (TERM_PROGRAM=ghostty,
         // #1445), and a few VTE terminals (#1470) produce visible flicker at
         // 120 FPS. Drop to the 30 FPS low-motion cap for them automatically.
@@ -604,22 +587,6 @@ impl Settings {
             "prefer_external_pdftotext" | "external_pdftotext" | "pdftotext" => {
                 self.prefer_external_pdftotext = parse_bool(value)?;
             }
-            "voice_input_command" | "voice_command" | "dictation_command" => {
-                self.voice_input_command = normalize_optional_voice_input_command(Some(value));
-            }
-            "voice_input_timeout_secs" | "voice_timeout" | "dictation_timeout" => {
-                let timeout_secs: u64 = value.parse().map_err(|_| {
-                    anyhow::anyhow!(
-                        "Failed to update setting: invalid voice input timeout '{value}'. Expected a number from 1 to 600."
-                    )
-                })?;
-                if !(1..=600).contains(&timeout_secs) {
-                    anyhow::bail!(
-                        "Failed to update setting: voice input timeout must be between 1 and 600 seconds."
-                    );
-                }
-                self.voice_input_timeout_secs = timeout_secs;
-            }
             "default_mode" | "mode" => {
                 let normalized = normalize_mode(value);
                 if !["agent", "plan", "yolo"].contains(&normalized) {
@@ -748,16 +715,6 @@ impl Settings {
             "  prefer_external_pdftotext: {}",
             self.prefer_external_pdftotext
         ));
-        lines.push(format!(
-            "  voice_input_command: {}",
-            self.voice_input_command
-                .as_deref()
-                .unwrap_or("(not configured)")
-        ));
-        lines.push(format!(
-            "  voice_input_timeout_secs: {}",
-            self.voice_input_timeout_secs
-        ));
         lines.push(format!("  default_mode:       {}", self.default_mode));
         lines.push(format!(
             "  sidebar_width:      {}%",
@@ -813,6 +770,10 @@ impl Settings {
             ),
             ("show_thinking", "Show model thinking: on/off"),
             ("show_tool_details", "Show detailed tool output: on/off"),
+            (
+                "base_url",
+                "HTTP base URL for DeepSeek-compatible endpoints.",
+            ),
             (
                 "locale",
                 "UI locale and default model language: auto, en, ja, zh-Hans, pt-BR, es-419",
@@ -850,14 +811,6 @@ impl Settings {
                 "prefer_external_pdftotext",
                 "Route PDF reads through Poppler's pdftotext instead of the bundled pure-Rust extractor: on/off (default off)",
             ),
-            (
-                "voice_input_command",
-                "Command run by command-palette Voice input; stdout must be the transcript, or none/default to disable",
-            ),
-            (
-                "voice_input_timeout_secs",
-                "Voice input command timeout in seconds: 1-600 (default 60)",
-            ),
             ("default_mode", "Default mode: agent, plan, yolo"),
             ("sidebar_width", "Sidebar width percentage: 10-50"),
             (
@@ -1078,24 +1031,6 @@ fn normalize_background_color_setting(value: &str) -> Result<Option<String>> {
     })
 }
 
-fn normalize_optional_voice_input_command(value: Option<&str>) -> Option<String> {
-    value.and_then(normalize_voice_input_command)
-}
-
-fn normalize_voice_input_command(value: &str) -> Option<String> {
-    let trimmed = value.trim();
-    if trimmed.is_empty()
-        || matches!(
-            trimmed.to_ascii_lowercase().as_str(),
-            "default" | "none" | "off" | "false" | "disabled"
-        )
-    {
-        None
-    } else {
-        Some(trimmed.to_string())
-    }
-}
-
 fn normalize_sidebar_focus(value: &str) -> &str {
     match value.trim().to_ascii_lowercase().as_str() {
         "work" | "plan" | "todos" => "work",
@@ -1308,39 +1243,6 @@ mod tests {
         assert!(!settings.context_panel);
     }
 
-    #[test]
-    fn voice_input_settings_normalize_and_clear() {
-        let mut settings = Settings::default();
-        assert!(settings.voice_input_command.is_none());
-        assert_eq!(
-            settings.voice_input_timeout_secs,
-            crate::tui::voice_input::default_timeout_secs()
-        );
-
-        settings
-            .set("voice_input_command", r#"python3 "/tmp/voice helper.py""#)
-            .expect("set voice command");
-        assert_eq!(
-            settings.voice_input_command.as_deref(),
-            Some(r#"python3 "/tmp/voice helper.py""#)
-        );
-
-        settings
-            .set("voice_input_timeout_secs", "120")
-            .expect("set timeout");
-        assert_eq!(settings.voice_input_timeout_secs, 120);
-
-        settings
-            .set("voice_command", "none")
-            .expect("clear voice command");
-        assert!(settings.voice_input_command.is_none());
-
-        let err = settings
-            .set("voice_timeout", "0")
-            .expect_err("timeout must be bounded");
-        assert!(err.to_string().contains("between 1 and 600"));
-    }
-
     #[test]
     fn display_localizes_header_and_config_file_label() {
         let settings = Settings::default();
@@ -1422,15 +1324,28 @@ mod tests {
         let prev_wt_session = std::env::var_os("WT_SESSION");
         let prev_tmux = std::env::var_os("TMUX");
         let prev_sty = std::env::var_os("STY");
+        let prev_term_program = std::env::var_os("TERM_PROGRAM");
+        let prev_ssh_client = std::env::var_os("SSH_CLIENT");
+        let prev_ssh_tty = std::env::var_os("SSH_TTY");
+        let prev_tilix_id = std::env::var_os("TILIX_ID");
+        let prev_terminator_uuid = std::env::var_os("TERMINATOR_UUID");
+
         // The test is about NO_ANIMATIONS only. On Windows CI, an unmarked
         // console host now independently enables low_motion, so mark the host
         // as non-legacy while checking falsy spellings.
         // Clear multiplexer markers for the same reason: they also force
         // low_motion independently of NO_ANIMATIONS.
+        // Clear TERM_PROGRAM, SSH, and other terminal-specific variables as they
+        // also force low_motion independently of NO_ANIMATIONS.
         // SAFETY: serialised by the guard.
         unsafe {
             std::env::remove_var("TMUX");
             std::env::remove_var("STY");
+            std::env::remove_var("TERM_PROGRAM");
+            std::env::remove_var("SSH_CLIENT");
+            std::env::remove_var("SSH_TTY");
+            std::env::remove_var("TILIX_ID");
+            std::env::remove_var("TERMINATOR_UUID");
         }
         #[cfg(windows)]
         unsafe {
@@ -1469,6 +1384,26 @@ mod tests {
                 Some(v) => std::env::set_var("STY", v),
                 None => std::env::remove_var("STY"),
             }
+            match prev_term_program {
+                Some(v) => std::env::set_var("TERM_PROGRAM", v),
+                None => std::env::remove_var("TERM_PROGRAM"),
+            }
+            match prev_ssh_client {
+                Some(v) => std::env::set_var("SSH_CLIENT", v),
+                None => std::env::remove_var("SSH_CLIENT"),
+            }
+            match prev_ssh_tty {
+                Some(v) => std::env::set_var("SSH_TTY", v),
+                None => std::env::remove_var("SSH_TTY"),
+            }
+            match prev_tilix_id {
+                Some(v) => std::env::set_var("TILIX_ID", v),
+                None => std::env::remove_var("TILIX_ID"),
+            }
+            match prev_terminator_uuid {
+                Some(v) => std::env::set_var("TERMINATOR_UUID", v),
+                None => std::env::remove_var("TERMINATOR_UUID"),
+            }
         }
     }
 
diff --git a/crates/tui/src/shell_dispatcher.rs b/crates/tui/src/shell_dispatcher.rs
new file mode 100644
index 00000000..b4af5220
--- /dev/null
+++ b/crates/tui/src/shell_dispatcher.rs
@@ -0,0 +1,565 @@
+//! Shell abstraction layer for DeepSeek TUI.
+//!
+//! Detects the user's shell at startup and provides a single entry point for
+//! all command execution. DeepSeek TUI never calls `Command::new("cmd")` (or
+//! `"sh"`, `"pwsh"`, ...) directly — it asks the [`ShellDispatcher`] to build
+//! a correctly configured [`std::process::Command`].
+//!
+//! ## Responsibilities
+//!
+//! 1. **Shell detection** — find the user's actual shell (PowerShell, pwsh,
+//!    bash via WSL / Git Bash, cmd.exe fallback on Windows, /bin/sh on Unix).
+//! 2. **Quoting correctness** — each shell's argument-passing convention is
+//!    respected so quoted strings survive the spawn boundary intact.
+//! 3. **Terminal state** — foreground shell execution saves and restores
+//!    crossterm raw-mode so the TUI input pipeline is not broken after a
+//!    child process exits (issue #1690).
+
+use std::fs::OpenOptions;
+use std::io::Write;
+#[cfg(windows)]
+use std::os::windows::process::CommandExt;
+use std::path::Path;
+use std::process::Command;
+use std::sync::Mutex;
+
+static LOG_MUTEX: Mutex<()> = Mutex::new(());
+
+// ---------------------------------------------------------------------------
+// Shell kind
+// ---------------------------------------------------------------------------
+
+/// The concrete shell that the dispatcher will use.
+#[allow(dead_code)]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ShellKind {
+    /// PowerShell 7+ (`pwsh.exe`).
+    Pwsh,
+    /// Windows PowerShell 5.1 (`powershell.exe`).
+    WindowsPowerShell,
+    /// Command Prompt (`cmd.exe`).
+    Cmd,
+    /// Unix `/bin/sh` (or `$SHELL`-detected bash/zsh).
+    Sh,
+    /// Bash — detected via `$SHELL` on either Unix or WSL/Git Bash on Windows.
+    Bash,
+    /// Any other POSIX shell from $SHELL (zsh, fish, dash, ...).
+    Custom { binary: String, flag: String },
+}
+
+impl ShellKind {
+    /// Binary name for the shell. Appends `.exe` on Windows where needed.
+    pub fn binary(&self) -> &str {
+        match self {
+            #[cfg(windows)]
+            ShellKind::Pwsh => "pwsh.exe",
+            #[cfg(not(windows))]
+            ShellKind::Pwsh => "pwsh",
+
+            #[cfg(windows)]
+            ShellKind::WindowsPowerShell => "powershell.exe",
+            #[cfg(not(windows))]
+            ShellKind::WindowsPowerShell => "powershell",
+
+            #[cfg(windows)]
+            ShellKind::Cmd => "cmd.exe",
+            #[cfg(not(windows))]
+            ShellKind::Cmd => "cmd",
+
+            ShellKind::Sh => "sh",
+            ShellKind::Bash => "bash",
+            ShellKind::Custom { binary, .. } => binary,
+        }
+    }
+
+    /// Flag that tells the shell to execute the following argument as a
+    /// command string.
+    pub fn command_flag(&self) -> &str {
+        match self {
+            ShellKind::Pwsh | ShellKind::WindowsPowerShell => "-NoProfile",
+            ShellKind::Cmd => "/C",
+            ShellKind::Sh | ShellKind::Bash => "-c",
+            ShellKind::Custom { flag, .. } => flag,
+        }
+    }
+
+    /// Whether this shell needs an extra `-Command` flag after the profile
+    /// flag (PowerShell-specific).
+    pub fn needs_command_flag(&self) -> bool {
+        matches!(self, ShellKind::Pwsh | ShellKind::WindowsPowerShell)
+    }
+
+    #[cfg(test)]
+    /// Returns true when this is a PowerShell-family shell.
+    pub fn is_powershell(&self) -> bool {
+        matches!(self, ShellKind::Pwsh | ShellKind::WindowsPowerShell)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher
+// ---------------------------------------------------------------------------
+
+/// Central shell abstraction. Created once at startup via
+/// [`ShellDispatcher::detect`] and then used everywhere a command needs to
+/// be spawned.
+#[derive(Debug, Clone)]
+pub struct ShellDispatcher {
+    kind: ShellKind,
+}
+
+#[allow(dead_code)]
+impl ShellDispatcher {
+    /// Detect the user's shell from the environment.
+    ///
+    /// ## Detection order (Windows)
+    ///
+    /// 1. `$env:SHELL` — WSL interop or Git Bash often set this.
+    /// 2. `pwsh.exe` found on `PATH` — PowerShell 7+.
+    /// 3. `powershell.exe` found on `PATH` — Windows PowerShell 5.1.
+    /// 4. `cmd.exe` — always available, last resort.
+    ///
+    /// ## Detection order (Unix)
+    ///
+    /// 1. `$SHELL` — if it contains `bash`, use `Bash`; otherwise use the
+    ///    actual binary path via `Custom`.
+    /// 2. `/bin/sh` fallback.
+    pub fn detect() -> Self {
+        let kind = Self::detect_shell();
+        Self::log_startup(&kind);
+        ShellDispatcher { kind }
+    }
+
+    /// Log a shell execution line when `SHELL_DISPATCHER_LOG` is set.
+    pub fn log_exec(command: &str) {
+        if let Ok(path) = std::env::var("SHELL_DISPATCHER_LOG") {
+            let _ = Self::append_log_static(&path, command);
+        }
+    }
+
+    fn log_startup(kind: &ShellKind) {
+        let _lock = LOG_MUTEX.lock();
+        if let Ok(path) = std::env::var("SHELL_DISPATCHER_LOG") {
+            let init_line = format!(
+                "--- ShellDispatcher log started pid={} ---\n",
+                std::process::id()
+            );
+            let _ = Self::append_log(&path, &init_line);
+            let detect_line = format!("[{}] detect: {kind:?}\n", now_iso());
+            let _ = Self::append_log(&path, &detect_line);
+        }
+    }
+
+    fn append_log(path: &str, line: &str) -> std::io::Result<()> {
+        let mut file = OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(Path::new(path))?;
+        file.write_all(line.as_bytes())?;
+        file.flush()
+    }
+
+    fn append_log_static(path: &str, command: &str) -> std::io::Result<()> {
+        // Resolve kind outside the lock — `global_dispatcher()` may trigger
+        // `detect()` which calls `log_startup()` which also acquires the mutex.
+        let kind = global_dispatcher().kind();
+        let _lock = LOG_MUTEX.lock();
+        let line = format!("[{}] exec via {kind:?}: {command}\n", now_iso());
+        Self::append_log(path, &line)
+    }
+
+    /// The detected shell kind.
+    pub fn kind(&self) -> &ShellKind {
+        &self.kind
+    }
+
+    // -- Public builders --------------------------------------------------
+
+    /// Build a `std::process::Command` for the given shell command string.
+    pub fn build_command(&self, shell_command: &str) -> Command {
+        let mut cmd = Command::new(self.kind.binary());
+
+        if self.kind.needs_command_flag() {
+            cmd.arg(self.kind.command_flag());
+            cmd.arg("-Command");
+            cmd.arg(shell_command);
+        } else if matches!(self.kind, ShellKind::Cmd) {
+            cmd.arg(self.kind.command_flag());
+            #[cfg(windows)]
+            {
+                cmd.raw_arg(shell_command);
+            }
+            #[cfg(not(windows))]
+            {
+                cmd.arg(shell_command);
+            }
+        } else {
+            cmd.arg(self.kind.command_flag());
+            cmd.arg(shell_command);
+        }
+
+        cmd
+    }
+
+    /// Build the program + args tuple. Useful when the caller needs to
+    /// inspect or modify the args before passing them to `Command`.
+    pub fn build_command_parts(&self, shell_command: &str) -> (String, Vec<String>) {
+        let program = self.kind.binary().to_string();
+        let args = if self.kind.needs_command_flag() {
+            vec![
+                self.kind.command_flag().to_string(),
+                "-Command".to_string(),
+                shell_command.to_string(),
+            ]
+        } else {
+            vec![
+                self.kind.command_flag().to_string(),
+                shell_command.to_string(),
+            ]
+        };
+        (program, args)
+    }
+
+    /// Build a `Command` from separate program + args (bypasses the shell).
+    /// Used when the caller already has a resolved executable and argument
+    /// vector — e.g. `ExecEnv` from the sandbox.
+    #[cfg(test)]
+    pub fn build_direct(&self, program: &str, args: &[String]) -> Command {
+        let mut cmd = Command::new(program);
+        cmd.args(args);
+        cmd
+    }
+
+    /// Execute a foreground command with raw-mode save/restore.
+    ///
+    /// A scope guard ensures raw mode is restored even if the command fails
+    /// to spawn or returns early (review feedback, issue #1690).
+    pub fn run_foreground(
+        &self,
+        shell_command: &str,
+        cwd: &std::path::Path,
+    ) -> Result<String, anyhow::Error> {
+        use anyhow::Context;
+
+        // Log the execution
+        {
+            let _lock = LOG_MUTEX.lock();
+            if let Ok(path) = std::env::var("SHELL_DISPATCHER_LOG") {
+                let kind = self.kind();
+                let line = format!("[{}] exec via {kind:?}: {shell_command}\n", now_iso());
+                let _ = Self::append_log(&path, &line);
+            }
+        }
+
+        // Disable raw mode; guard restores it only if it was already enabled.
+        let raw_mode_was_enabled = crossterm::terminal::is_raw_mode_enabled().unwrap_or(false);
+        if raw_mode_was_enabled {
+            let _ = crossterm::terminal::disable_raw_mode();
+        }
+        struct FgRawModeGuard {
+            restore: bool,
+        }
+        impl Drop for FgRawModeGuard {
+            fn drop(&mut self) {
+                if self.restore {
+                    let _ = crossterm::terminal::enable_raw_mode();
+                }
+            }
+        }
+        let _guard = FgRawModeGuard {
+            restore: raw_mode_was_enabled,
+        };
+
+        let mut cmd = self.build_command(shell_command);
+        cmd.current_dir(cwd);
+
+        let output = cmd
+            .output()
+            .with_context(|| format!("failed to execute shell command: {shell_command}"))?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            anyhow::bail!(
+                "shell command failed (status={}): {}",
+                output.status,
+                stderr.trim()
+            );
+        }
+
+        let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
+        Ok(stdout)
+    }
+
+    // -- Detection --------------------------------------------------------
+
+    fn detect_shell() -> ShellKind {
+        #[cfg(windows)]
+        {
+            // 1. $env:SHELL — WSL interop or Git Bash often set this.
+            if let Ok(shell) = std::env::var("SHELL") {
+                let lower = shell.to_lowercase();
+                if lower.contains("bash") {
+                    return ShellKind::Bash;
+                }
+                if lower.contains("pwsh") {
+                    return ShellKind::Pwsh;
+                }
+                if lower.contains("powershell") {
+                    return ShellKind::WindowsPowerShell;
+                }
+            }
+
+            if Self::find_exe("pwsh.exe") {
+                return ShellKind::Pwsh;
+            }
+            if Self::find_exe("powershell.exe") {
+                return ShellKind::WindowsPowerShell;
+            }
+            return ShellKind::Cmd;
+        }
+
+        #[cfg(not(windows))]
+        {
+            // 1. $SHELL environment variable (Unix)
+            if let Ok(shell) = std::env::var("SHELL") {
+                let lower = shell.to_lowercase();
+                if lower.contains("bash") {
+                    return ShellKind::Bash;
+                }
+                if lower.contains("pwsh") {
+                    return ShellKind::Pwsh;
+                }
+                if lower.contains("powershell") {
+                    return ShellKind::WindowsPowerShell;
+                }
+                return ShellKind::Custom {
+                    binary: shell,
+                    flag: "-c".to_string(),
+                };
+            }
+
+            ShellKind::Sh
+        }
+    }
+
+    /// Check PATH first, then fall back to well-known install directories.
+    #[cfg(windows)]
+    fn find_exe(name: &str) -> bool {
+        if Self::binary_on_path(name) {
+            return true;
+        }
+        // Well-known install locations (order by preference).
+        let known_dirs: &[&str] = &[
+            r"C:\Program Files\PowerShell\7",
+            r"C:\Windows\System32\WindowsPowerShell\v1.0",
+        ];
+        known_dirs
+            .iter()
+            .any(|dir| std::path::Path::new(dir).join(name).is_file())
+    }
+
+    #[cfg(windows)]
+    fn binary_on_path(name: &str) -> bool {
+        std::env::var_os("PATH")
+            .map(|path| {
+                std::env::split_paths(&path).any(|dir| {
+                    let candidate = dir.join(name);
+                    candidate.is_file()
+                })
+            })
+            .unwrap_or(false)
+    }
+}
+
+// -- Helpers ---------------------------------------------------------------
+
+fn now_iso() -> String {
+    chrono::Utc::now()
+        .format("%Y-%m-%dT%H:%M:%S%.3f")
+        .to_string()
+}
+
+/// Global dispatcher instance, detected once at startup.
+///
+/// Any code path that needs to spawn a shell command can use
+/// `global_dispatcher()` instead of threading the dispatcher through
+/// every function signature.
+pub fn global_dispatcher() -> &'static ShellDispatcher {
+    use std::sync::LazyLock;
+    static DISPATCHER: LazyLock<ShellDispatcher> = LazyLock::new(ShellDispatcher::detect);
+    &DISPATCHER
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shell_kind_binary_names() {
+        #[cfg(windows)]
+        {
+            assert_eq!(ShellKind::Pwsh.binary(), "pwsh.exe");
+            assert_eq!(ShellKind::WindowsPowerShell.binary(), "powershell.exe");
+            assert_eq!(ShellKind::Cmd.binary(), "cmd.exe");
+        }
+        #[cfg(not(windows))]
+        {
+            assert_eq!(ShellKind::Pwsh.binary(), "pwsh");
+            assert_eq!(ShellKind::WindowsPowerShell.binary(), "powershell");
+            assert_eq!(ShellKind::Cmd.binary(), "cmd");
+        }
+        assert_eq!(ShellKind::Sh.binary(), "sh");
+        assert_eq!(ShellKind::Bash.binary(), "bash");
+    }
+
+    #[test]
+    fn detect_returns_some_shell() {
+        let dispatcher = global_dispatcher();
+        let _kind = dispatcher.kind();
+    }
+
+    #[test]
+    fn powershell_build_command_includes_no_profile_and_command_flags() {
+        let dispatcher = ShellDispatcher {
+            kind: ShellKind::Pwsh,
+        };
+        let cmd = dispatcher.build_command("echo hello");
+        let args: Vec<&str> = cmd.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert!(args.contains(&"-NoProfile"));
+        assert!(args.contains(&"-Command"));
+        assert!(args.contains(&"echo hello"));
+    }
+
+    #[test]
+    fn cmd_build_command_uses_c_flag() {
+        let dispatcher = ShellDispatcher {
+            kind: ShellKind::Cmd,
+        };
+        let cmd = dispatcher.build_command("echo hello");
+        let args: Vec<&str> = cmd.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert!(args.contains(&"/C"));
+        assert!(args.contains(&"echo hello"));
+    }
+
+    #[test]
+    fn sh_build_command_uses_dash_c() {
+        let dispatcher = ShellDispatcher {
+            kind: ShellKind::Sh,
+        };
+        let cmd = dispatcher.build_command("echo hello");
+        let args: Vec<&str> = cmd.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert!(args.contains(&"-c"));
+        assert!(args.contains(&"echo hello"));
+    }
+
+    #[cfg(test)]
+    #[test]
+    fn build_direct_preserves_args() {
+        let dispatcher = ShellDispatcher {
+            kind: ShellKind::Cmd,
+        };
+        let args = vec!["-m".to_string(), "commit message".to_string()];
+        let cmd = dispatcher.build_direct("git", &args);
+        let cmd_args: Vec<&str> = cmd.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert_eq!(cmd_args, vec!["-m", "commit message"]);
+    }
+
+    #[cfg(test)]
+    #[test]
+    fn powershell_flags_are_correct() {
+        assert!(ShellKind::Pwsh.needs_command_flag());
+        assert!(ShellKind::WindowsPowerShell.needs_command_flag());
+        assert!(!ShellKind::Cmd.needs_command_flag());
+        assert!(!ShellKind::Sh.needs_command_flag());
+        assert!(!ShellKind::Bash.needs_command_flag());
+    }
+
+    #[cfg(test)]
+    #[test]
+    fn is_powershell_detects_both_variants() {
+        assert!(ShellKind::Pwsh.is_powershell());
+        assert!(ShellKind::WindowsPowerShell.is_powershell());
+        assert!(!ShellKind::Cmd.is_powershell());
+        assert!(!ShellKind::Sh.is_powershell());
+        assert!(!ShellKind::Bash.is_powershell());
+    }
+
+    #[cfg(test)]
+    #[test]
+    fn build_command_quotes_spaces_for_cmd() {
+        let dispatcher = ShellDispatcher {
+            kind: ShellKind::Cmd,
+        };
+        let cmd = dispatcher.build_command("git commit -m \"msg with spaces\"");
+        let args: Vec<&str> = cmd.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert_eq!(args.len(), 2);
+        assert_eq!(args[0], "/C");
+        assert!(args[1].contains("msg with spaces"));
+        assert!(args[1].starts_with("git "));
+    }
+
+    #[cfg(test)]
+    #[test]
+    fn build_command_quotes_spaces_for_pwsh() {
+        let dispatcher = ShellDispatcher {
+            kind: ShellKind::Pwsh,
+        };
+        let cmd = dispatcher.build_command("git commit -m \"msg with spaces\"");
+        let args: Vec<&str> = cmd.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert_eq!(args.len(), 3);
+        assert_eq!(args[0], "-NoProfile");
+        assert_eq!(args[1], "-Command");
+        assert!(args[2].contains("msg with spaces"));
+    }
+
+    #[cfg(test)]
+    #[test]
+    fn build_direct_handles_empty_args() {
+        let dispatcher = ShellDispatcher {
+            kind: ShellKind::Sh,
+        };
+        let cmd = dispatcher.build_direct("echo", &[]);
+        let args: Vec<&str> = cmd.get_args().map(|a| a.to_str().unwrap()).collect();
+        assert!(args.is_empty());
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn find_exe_finds_cmd_on_path() {
+        // cmd.exe is always on PATH on Windows.
+        assert!(ShellDispatcher::find_exe("cmd.exe"));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn find_exe_rejects_nonexistent_binary() {
+        assert!(!ShellDispatcher::find_exe("nonexistent_xyz_12345.exe"));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn find_exe_falls_back_to_known_dirs() {
+        // Verify the known-dirs fallback path actually exists on this system.
+        let ps_path = r"C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe";
+        if std::path::Path::new(ps_path).is_file() {
+            // The fallback directory exists — find_exe should locate it.
+            assert!(ShellDispatcher::find_exe("powershell.exe"));
+        } else {
+            eprintln!("Skipping: {ps_path} not present on this system");
+        }
+    }
+
+    #[test]
+    fn custom_shell_uses_provided_binary_and_flag() {
+        let kind = ShellKind::Custom {
+            binary: "/bin/zsh".to_string(),
+            flag: "-c".to_string(),
+        };
+        assert_eq!(kind.binary(), "/bin/zsh");
+        assert_eq!(kind.command_flag(), "-c");
+    }
+}
diff --git a/crates/tui/src/skill_state.rs b/crates/tui/src/skill_state.rs
index 4816fa8e..245b51f3 100644
--- a/crates/tui/src/skill_state.rs
+++ b/crates/tui/src/skill_state.rs
@@ -5,7 +5,7 @@
 //! filesystem-discovered `SkillRegistry`: the registry tells us which skills
 //! exist on disk, and this store tells API clients which ones are marked active.
 //!
-//! Storage shape (TOML at `~/.deepseek/skills_state.toml`):
+//! Storage shape (TOML at `~/.codewhale/skills_state.toml`, legacy `~/.deepseek/skills_state.toml`):
 //!
 //! ```toml
 //! disabled = ["skill-name-1", "skill-name-2"]
@@ -104,10 +104,8 @@ impl SkillStateStore {
 }
 
 fn default_state_path() -> Result<PathBuf> {
-    let home = dirs::home_dir().context("could not resolve $HOME for ~/.deepseek")?;
-    let dir = home.join(".deepseek");
-    fs::create_dir_all(&dir)
-        .with_context(|| format!("create deepseek state dir at {}", dir.display()))?;
+    let dir = codewhale_config::ensure_state_dir(".")
+        .context("could not resolve or create CodeWhale state directory")?;
     Ok(dir.join(STATE_FILE_NAME))
 }
 
diff --git a/crates/tui/src/skills/install.rs b/crates/tui/src/skills/install.rs
index 53e641fb..787b6c4a 100644
--- a/crates/tui/src/skills/install.rs
+++ b/crates/tui/src/skills/install.rs
@@ -52,7 +52,7 @@ use crate::network_policy::{Decision, NetworkPolicy, host_from_url};
 pub fn default_cache_skills_dir() -> PathBuf {
     dirs::home_dir().map_or_else(
         || PathBuf::from("/tmp/codewhale/cache/skills"),
-        |p| p.join(".deepseek").join("cache").join("skills"),
+        |p| p.join(".codewhale").join("cache").join("skills"),
     )
 }
 
@@ -391,7 +391,10 @@ pub async fn update_with_registry(
     network: &NetworkPolicy,
     registry_url: &str,
 ) -> Result<UpdateResult> {
-    let target = skills_dir.join(name);
+    let target = skill_target_path(name, skills_dir)?;
+    if target.exists() {
+        ensure_target_within_skills_dir(&target, skills_dir)?;
+    }
     let marker_path = target.join(INSTALLED_FROM_MARKER);
     if !marker_path.exists() {
         return Err(InstallError::NotInstalledHere(name.to_string()).into());
@@ -439,10 +442,11 @@ pub async fn update_with_registry(
 /// Refuses to touch any directory that doesn't carry the `.installed-from`
 /// marker — that's our cue that it's user-owned and not a system skill.
 pub fn uninstall(name: &str, skills_dir: &Path) -> Result<()> {
-    let target = skills_dir.join(name);
+    let target = skill_target_path(name, skills_dir)?;
     if !target.exists() {
         bail!("skill '{name}' is not installed at {}", target.display());
     }
+    ensure_target_within_skills_dir(&target, skills_dir)?;
     if !target.join(INSTALLED_FROM_MARKER).exists() {
         return Err(InstallError::NotInstalledHere(name.to_string()).into());
     }
@@ -458,10 +462,11 @@ pub fn uninstall(name: &str, skills_dir: &Path) -> Result<()> {
 /// Refuses to mark system skills (no `.installed-from`) so the bundled
 /// `skill-creator` doesn't accidentally inherit elevated tool privileges.
 pub fn trust(name: &str, skills_dir: &Path) -> Result<()> {
-    let target = skills_dir.join(name);
+    let target = skill_target_path(name, skills_dir)?;
     if !target.exists() {
         bail!("skill '{name}' is not installed at {}", target.display());
     }
+    ensure_target_within_skills_dir(&target, skills_dir)?;
     if !target.join(INSTALLED_FROM_MARKER).exists() {
         return Err(InstallError::NotInstalledHere(name.to_string()).into());
     }
@@ -1343,6 +1348,40 @@ fn is_safe_path(path: &Path) -> bool {
     true
 }
 
+fn skill_target_path(name: &str, skills_dir: &Path) -> Result<PathBuf> {
+    let name = validate_skill_name_segment(name)?;
+    Ok(skills_dir.join(name))
+}
+
+fn validate_skill_name_segment(name: &str) -> Result<&str> {
+    if name.is_empty() || name.trim() != name || name.chars().any(char::is_whitespace) {
+        bail!("skill name must be a single path-safe segment (got '{name}')");
+    }
+    if name == "." || name == ".." || name.contains('/') || name.contains('\\') {
+        bail!("skill name must be a single path-safe segment (got '{name}')");
+    }
+    let mut components = Path::new(name).components();
+    if !matches!(components.next(), Some(Component::Normal(_))) || components.next().is_some() {
+        bail!("skill name must be a single path-safe segment (got '{name}')");
+    }
+    Ok(name)
+}
+
+fn ensure_target_within_skills_dir(target: &Path, skills_dir: &Path) -> Result<()> {
+    let skills_dir = fs::canonicalize(skills_dir)
+        .with_context(|| format!("failed to resolve {}", skills_dir.display()))?;
+    let target = fs::canonicalize(target)
+        .with_context(|| format!("failed to resolve {}", target.display()))?;
+    if !target.starts_with(&skills_dir) {
+        bail!(
+            "skill path {} escapes skills directory {}",
+            target.display(),
+            skills_dir.display()
+        );
+    }
+    Ok(())
+}
+
 /// Strip a leading directory prefix (e.g. `repo-main/`) from a tarball path.
 fn strip_prefix<'a>(path: &'a str, prefix: &str) -> std::borrow::Cow<'a, str> {
     if prefix.is_empty() {
@@ -1394,13 +1433,7 @@ fn parse_frontmatter_name(bytes: &[u8]) -> Result<String> {
     if !has_description {
         return Err(InstallError::MissingFrontmatterField("description").into());
     }
-    // Sanity check: name must be a single path-safe segment.
-    if name.contains('/')
-        || name.contains('\\')
-        || name == "."
-        || name == ".."
-        || name.contains(' ')
-    {
+    if validate_skill_name_segment(&name).is_err() {
         bail!("SKILL.md `name` must be a single path-safe segment (got '{name}')");
     }
     Ok(name)
@@ -1546,6 +1579,9 @@ mod tests {
 
         let body = b"---\nname: a name with spaces\ndescription: x\n---\n";
         assert!(parse_frontmatter_name(body).is_err());
+
+        let body = b"---\nname: tab\tname\ndescription: x\n---\n";
+        assert!(parse_frontmatter_name(body).is_err());
     }
 
     #[test]
@@ -1554,6 +1590,66 @@ mod tests {
         assert!(parse_frontmatter_name(body).is_err());
     }
 
+    #[test]
+    fn user_skill_names_must_be_single_safe_segments() {
+        for bad in [
+            "",
+            "../evil",
+            "/tmp/evil",
+            "two words",
+            "two\twords",
+            "evil/name",
+            "evil\\name",
+            ".",
+            "..",
+            " leading",
+            "trailing ",
+        ] {
+            assert!(
+                validate_skill_name_segment(bad).is_err(),
+                "expected {bad:?} to be rejected"
+            );
+        }
+        assert_eq!(
+            validate_skill_name_segment("safe-name_1").unwrap(),
+            "safe-name_1"
+        );
+    }
+
+    #[test]
+    fn uninstall_and_trust_reject_unsafe_skill_names_before_path_join() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let skills_dir = tmp.path().join("skills");
+        std::fs::create_dir_all(&skills_dir).expect("skills dir");
+
+        for bad in [
+            "../evil",
+            "/tmp/evil",
+            "evil/name",
+            "evil\\name",
+            "two words",
+        ] {
+            assert!(uninstall(bad, &skills_dir).is_err());
+            assert!(trust(bad, &skills_dir).is_err());
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn uninstall_rejects_symlink_target_escaping_skills_dir() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let skills_dir = tmp.path().join("skills");
+        let outside = tmp.path().join("outside");
+        std::fs::create_dir_all(&skills_dir).expect("skills dir");
+        std::fs::create_dir_all(&outside).expect("outside dir");
+        std::fs::write(outside.join(INSTALLED_FROM_MARKER), "{}").expect("marker");
+        std::os::unix::fs::symlink(&outside, skills_dir.join("linked")).expect("symlink");
+
+        let err = uninstall("linked", &skills_dir).unwrap_err();
+        assert!(err.to_string().contains("escapes skills directory"));
+        assert!(outside.exists());
+    }
+
     #[test]
     fn strip_prefix_handles_all_cases() {
         assert_eq!(strip_prefix("foo/bar", "foo"), "bar");
diff --git a/crates/tui/src/skills/mod.rs b/crates/tui/src/skills/mod.rs
index d962d32e..d2c2f6ad 100644
--- a/crates/tui/src/skills/mod.rs
+++ b/crates/tui/src/skills/mod.rs
@@ -580,6 +580,10 @@ fn discover_for_workspace_dirs_and_dir(mut dirs: Vec<PathBuf>, skills_dir: &Path
         dirs.push(skills_dir.to_path_buf());
     }
 
+    discover_from_directories(dirs)
+}
+
+pub(crate) fn discover_from_directories(dirs: impl IntoIterator<Item = PathBuf>) -> SkillRegistry {
     let mut merged = SkillRegistry::default();
     for dir in dirs {
         let registry = SkillRegistry::discover(&dir);
diff --git a/crates/tui/src/slop_ledger.rs b/crates/tui/src/slop_ledger.rs
new file mode 100644
index 00000000..30571252
--- /dev/null
+++ b/crates/tui/src/slop_ledger.rs
@@ -0,0 +1,1286 @@
+//! Slop Ledger — durable tracking of unresolved architectural residue.
+//!
+//! AI agents often leave behind invisible "slop" after a task:
+//! compatibility shims, unmigrated callers, duplicated concepts,
+//! naming drift, stale docs/tests, suspected dead code, and tool gaps.
+//!
+//! The Slop Ledger makes this residue **visible and queryable** so the
+//! next agent (or human) doesn't rediscover it, amplify it, or mistake
+//! it for intended architecture.
+//!
+//! ## Design
+//!
+//! - **Storage**: `~/.codewhale/slop_ledger.json` (a JSON array of entries).
+//! - **Schema**: each entry has a bucket, severity, confidence, owner,
+//!   source links, status, cleanup recommendation, and timestamps.
+//! - **Tools**: `slop_ledger_append`, `slop_ledger_query`,
+//!   `slop_ledger_update`, `slop_ledger_export`.
+//! - **Integration**: entries can link to durable tasks and threads;
+//!   the export path produces a redacted Markdown handoff suitable for
+//!   GitHub issues or compaction relays.
+
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::fs;
+use std::io;
+use std::path::PathBuf;
+use uuid::Uuid;
+
+use crate::tools::spec::{
+    ApprovalRequirement, ToolCapability, ToolContext, ToolError, ToolResult, ToolSpec, required_str,
+};
+
+// ── Enums ──────────────────────────────────────────────────────────────────
+
+/// Classification bucket for a slop entry.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SlopBucket {
+    RetainedCompatibility,
+    UnmigratedCallers,
+    DuplicateConcepts,
+    NamingDrift,
+    StaleDocs,
+    StaleTests,
+    SuspectedDeadCode,
+    UnverifiedPublicBehavior,
+    ToolGaps,
+    AcceptedDebt,
+}
+
+impl SlopBucket {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::RetainedCompatibility => "retained_compatibility",
+            Self::UnmigratedCallers => "unmigrated_callers",
+            Self::DuplicateConcepts => "duplicate_concepts",
+            Self::NamingDrift => "naming_drift",
+            Self::StaleDocs => "stale_docs",
+            Self::StaleTests => "stale_tests",
+            Self::SuspectedDeadCode => "suspected_dead_code",
+            Self::UnverifiedPublicBehavior => "unverified_public_behavior",
+            Self::ToolGaps => "tool_gaps",
+            Self::AcceptedDebt => "accepted_debt",
+        }
+    }
+
+    pub fn from_str(s: &str) -> Option<Self> {
+        match s.trim().to_lowercase().as_str() {
+            "retained_compatibility" => Some(Self::RetainedCompatibility),
+            "unmigrated_callers" => Some(Self::UnmigratedCallers),
+            "duplicate_concepts" => Some(Self::DuplicateConcepts),
+            "naming_drift" => Some(Self::NamingDrift),
+            "stale_docs" => Some(Self::StaleDocs),
+            "stale_tests" => Some(Self::StaleTests),
+            "suspected_dead_code" => Some(Self::SuspectedDeadCode),
+            "unverified_public_behavior" => Some(Self::UnverifiedPublicBehavior),
+            "tool_gaps" => Some(Self::ToolGaps),
+            "accepted_debt" => Some(Self::AcceptedDebt),
+            _ => None,
+        }
+    }
+
+    #[allow(dead_code)]
+    pub fn all_buckets() -> &'static [SlopBucket] {
+        &[
+            Self::RetainedCompatibility,
+            Self::UnmigratedCallers,
+            Self::DuplicateConcepts,
+            Self::NamingDrift,
+            Self::StaleDocs,
+            Self::StaleTests,
+            Self::SuspectedDeadCode,
+            Self::UnverifiedPublicBehavior,
+            Self::ToolGaps,
+            Self::AcceptedDebt,
+        ]
+    }
+}
+
+/// Severity of the residue.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SlopSeverity {
+    Critical,
+    High,
+    Medium,
+    Low,
+    Info,
+}
+
+impl SlopSeverity {
+    pub fn from_str(s: &str) -> Option<Self> {
+        match s.trim().to_lowercase().as_str() {
+            "critical" => Some(Self::Critical),
+            "high" => Some(Self::High),
+            "medium" => Some(Self::Medium),
+            "low" => Some(Self::Low),
+            "info" => Some(Self::Info),
+            _ => None,
+        }
+    }
+}
+
+/// Confidence in the assessment.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SlopConfidence {
+    Certain,
+    High,
+    Medium,
+    Low,
+}
+
+impl SlopConfidence {
+    pub fn from_str(s: &str) -> Option<Self> {
+        match s.trim().to_lowercase().as_str() {
+            "certain" => Some(Self::Certain),
+            "high" => Some(Self::High),
+            "medium" => Some(Self::Medium),
+            "low" => Some(Self::Low),
+            _ => None,
+        }
+    }
+}
+
+/// Lifecycle status of a slop entry.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SlopEntryStatus {
+    Open,
+    InProgress,
+    Resolved,
+    Accepted,
+    WontFix,
+}
+
+impl SlopEntryStatus {
+    pub fn from_str(s: &str) -> Option<Self> {
+        match s.trim().to_lowercase().as_str() {
+            "open" => Some(Self::Open),
+            "in_progress" | "inprogress" => Some(Self::InProgress),
+            "resolved" | "done" => Some(Self::Resolved),
+            "accepted" => Some(Self::Accepted),
+            "wontfix" | "wont_fix" => Some(Self::WontFix),
+            _ => None,
+        }
+    }
+}
+
+// ── Core data structures ───────────────────────────────────────────────────
+
+/// A single slop ledger entry.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SlopEntry {
+    /// Unique identifier (UUID v4).
+    pub id: String,
+    /// Classification bucket.
+    pub bucket: SlopBucket,
+    /// How severe is this residue?
+    pub severity: SlopSeverity,
+    /// How confident is the assessment?
+    pub confidence: SlopConfidence,
+    /// Who owns cleaning this up (person, team, or "auto").
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub owner: Option<String>,
+    /// Source file paths, URLs, or line references.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub source_links: Vec<String>,
+    /// Short title (one line).
+    pub title: String,
+    /// Detailed description.
+    pub description: String,
+    /// Current lifecycle status.
+    pub status: SlopEntryStatus,
+    /// Suggested cleanup action.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cleanup_recommendation: Option<String>,
+    /// ISO 8601 creation timestamp.
+    pub created_at: String,
+    /// ISO 8601 last-updated timestamp.
+    pub updated_at: String,
+    /// Optional linked durable task id.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub task_id: Option<String>,
+    /// Optional linked thread id.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub thread_id: Option<String>,
+}
+
+impl SlopEntry {
+    pub fn new(
+        bucket: SlopBucket,
+        severity: SlopSeverity,
+        confidence: SlopConfidence,
+        title: String,
+        description: String,
+    ) -> Self {
+        let now = chrono::Utc::now().to_rfc3339();
+        Self {
+            id: Uuid::new_v4().to_string(),
+            bucket,
+            severity,
+            confidence,
+            owner: None,
+            source_links: Vec::new(),
+            title,
+            description,
+            status: SlopEntryStatus::Open,
+            cleanup_recommendation: None,
+            created_at: now.clone(),
+            updated_at: now,
+            task_id: None,
+            thread_id: None,
+        }
+    }
+}
+
+// ── Query filter ───────────────────────────────────────────────────────────
+
+/// Filter for querying ledger entries.
+#[derive(Debug, Clone, Default)]
+pub struct SlopLedgerFilter {
+    pub bucket: Option<SlopBucket>,
+    pub severity: Option<SlopSeverity>,
+    pub status: Option<SlopEntryStatus>,
+    pub search: Option<String>, // fuzzy match title + description
+    pub limit: Option<usize>,
+}
+
+// ── Ledger (collection + persistence) ──────────────────────────────────────
+
+/// The slop ledger — a collection of entries with JSON file persistence.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct SlopLedger {
+    entries: Vec<SlopEntry>,
+    #[serde(skip)]
+    ledger_path: PathBuf,
+}
+
+impl SlopLedger {
+    /// Resolve the default ledger path.
+    pub fn default_path() -> io::Result<PathBuf> {
+        codewhale_config::resolve_state_dir("slop_ledger")
+            .map(|p| p.join("slop_ledger.json"))
+            .map_err(|e| io::Error::new(io::ErrorKind::Other, e))
+    }
+
+    /// Load ledger from the default path, returning an empty ledger if the
+    /// file doesn't exist.
+    pub fn load() -> io::Result<Self> {
+        let path = Self::default_path()?;
+        Self::load_at(&path)
+    }
+
+    /// Load ledger from a specific path.
+    pub fn load_at(path: &std::path::Path) -> io::Result<Self> {
+        if !path.exists() {
+            return Ok(Self {
+                entries: Vec::new(),
+                ledger_path: path.to_path_buf(),
+            });
+        }
+        let data = fs::read_to_string(path)?;
+        let mut ledger: SlopLedger = serde_json::from_str(&data).map_err(|e| {
+            io::Error::new(
+                io::ErrorKind::InvalidData,
+                format!("failed to parse slop ledger JSON: {e}"),
+            )
+        })?;
+        ledger.ledger_path = path.to_path_buf();
+        Ok(ledger)
+    }
+
+    /// Persist the ledger to disk.
+    pub fn save(&self) -> io::Result<()> {
+        if let Some(parent) = self.ledger_path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        let data = serde_json::to_string_pretty(self).map_err(|e| {
+            io::Error::new(io::ErrorKind::Other, format!("serialization error: {e}"))
+        })?;
+        crate::utils::write_atomic(&self.ledger_path, data.as_bytes())
+    }
+
+    /// Append one or more entries. Returns the new entry count and
+    /// the short ids of the appended entries.
+    pub fn append(&mut self, entries: Vec<SlopEntry>) -> (usize, Vec<String>) {
+        let ids: Vec<String> = entries.iter().map(|e| short_id(&e.id)).collect();
+        self.entries.extend(entries);
+        (self.entries.len(), ids)
+    }
+
+    /// Return the total number of entries.
+    #[must_use]
+    #[allow(dead_code)]
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// Whether the ledger is empty.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// Query entries matching the filter.
+    pub fn query(&self, filter: &SlopLedgerFilter) -> Vec<&SlopEntry> {
+        let mut results: Vec<&SlopEntry> = self
+            .entries
+            .iter()
+            .filter(|e| {
+                if let Some(bucket) = &filter.bucket {
+                    if e.bucket != *bucket {
+                        return false;
+                    }
+                }
+                if let Some(severity) = &filter.severity {
+                    if e.severity != *severity {
+                        return false;
+                    }
+                }
+                if let Some(status) = &filter.status {
+                    if e.status != *status {
+                        return false;
+                    }
+                }
+                if let Some(search) = &filter.search {
+                    let q = search.to_lowercase();
+                    if !e.title.to_lowercase().contains(&q)
+                        && !e.description.to_lowercase().contains(&q)
+                    {
+                        return false;
+                    }
+                }
+                true
+            })
+            .collect();
+
+        if let Some(limit) = filter.limit {
+            results.truncate(limit);
+        }
+        results
+    }
+
+    /// Find an entry by id.
+    pub fn find_mut(&mut self, id: &str) -> Option<&mut SlopEntry> {
+        self.entries.iter_mut().find(|e| e.id.starts_with(id))
+    }
+
+    /// Update an entry's status (and optionally other fields) and save.
+    pub fn update_status(
+        &mut self,
+        id: &str,
+        status: SlopEntryStatus,
+        cleanup_recommendation: Option<String>,
+    ) -> io::Result<Option<&SlopEntry>> {
+        let full_id = {
+            let entry = match self.find_mut(id) {
+                Some(e) => e,
+                None => return Ok(None),
+            };
+            entry.status = status;
+            entry.updated_at = chrono::Utc::now().to_rfc3339();
+            if let Some(rec) = cleanup_recommendation {
+                entry.cleanup_recommendation = Some(rec);
+            }
+            entry.id.clone()
+        };
+        self.save()?;
+        // Return a shared ref to the updated entry.
+        Ok(self.entries.iter().find(|e| e.id == full_id))
+    }
+
+    /// Export all entries as a Markdown string suitable for handoff or
+    /// GitHub issue body.
+    pub fn export_markdown(
+        &self,
+        title: Option<&str>,
+        filter: Option<&SlopLedgerFilter>,
+    ) -> String {
+        let entries: Vec<&SlopEntry> = match filter {
+            Some(f) => self.query(f),
+            None => self.entries.iter().collect(),
+        };
+
+        let heading = title.unwrap_or("Slop Ledger Export");
+        let mut out = format!("# {heading}\n\n");
+        out.push_str(&format!(
+            "_Generated at {} — {} entries_\n\n",
+            chrono::Utc::now().format("%Y-%m-%d %H:%M UTC").to_string(),
+            entries.len()
+        ));
+
+        if entries.is_empty() {
+            out.push_str("_(no entries)_\n");
+            return out;
+        }
+
+        // Group by bucket
+        use std::collections::BTreeMap;
+        let mut by_bucket: BTreeMap<&str, Vec<&&SlopEntry>> = BTreeMap::new();
+        for e in &entries {
+            by_bucket.entry(e.bucket.as_str()).or_default().push(e);
+        }
+
+        for (bucket_name, bucket_entries) in &by_bucket {
+            out.push_str(&format!("## {bucket_name}\n\n"));
+            out.push_str("| ID | Severity | Confidence | Status | Title | Source |\n");
+            out.push_str("|---|---|---|---|---|---|\n");
+            for e in bucket_entries {
+                let source = e.source_links.first().map(|s| s.as_str()).unwrap_or("-");
+                let title = truncate_str(&e.title, 60);
+                out.push_str(&format!(
+                    "| {} | {:?} | {:?} | {:?} | {title} | {source} |\n",
+                    short_id(&e.id),
+                    e.severity,
+                    e.confidence,
+                    e.status
+                ));
+            }
+            out.push('\n');
+
+            // Detailed entries
+            for e in bucket_entries {
+                out.push_str(&format!("### {} — {}\n\n", short_id(&e.id), e.title));
+                out.push_str(&format!("- **Severity**: {:?}\n", e.severity));
+                out.push_str(&format!("- **Confidence**: {:?}\n", e.confidence));
+                out.push_str(&format!("- **Status**: {:?}\n", e.status));
+                if let Some(ref owner) = e.owner {
+                    out.push_str(&format!("- **Owner**: {owner}\n"));
+                }
+                if !e.source_links.is_empty() {
+                    out.push_str("- **Sources**:\n");
+                    for link in &e.source_links {
+                        out.push_str(&format!("  - {link}\n"));
+                    }
+                }
+                out.push_str(&format!("\n{}\n", e.description));
+                if let Some(ref rec) = e.cleanup_recommendation {
+                    out.push_str(&format!("\n**Cleanup**: {rec}\n"));
+                }
+                out.push_str("\n---\n\n");
+            }
+        }
+
+        redact_exported_text(&mut out);
+        out
+    }
+
+    /// Summary counts by bucket and status — useful for quick display.
+    pub fn summary(&self) -> String {
+        use std::collections::BTreeMap;
+        let mut by_bucket: BTreeMap<&str, usize> = BTreeMap::new();
+        let mut open_count = 0usize;
+        let mut resolved_count = 0usize;
+        let mut accepted_count = 0usize;
+
+        for e in &self.entries {
+            *by_bucket.entry(e.bucket.as_str()).or_default() += 1;
+            match e.status {
+                SlopEntryStatus::Resolved => resolved_count += 1,
+                SlopEntryStatus::Accepted | SlopEntryStatus::WontFix => accepted_count += 1,
+                _ => open_count += 1,
+            }
+        }
+
+        let mut out = format!(
+            "Slop Ledger: {} total | {} open | {} resolved | {} accepted\n",
+            self.entries.len(),
+            open_count,
+            resolved_count,
+            accepted_count
+        );
+        for (bucket, count) in &by_bucket {
+            out.push_str(&format!("  {bucket}: {count}\n"));
+        }
+        redact_exported_text(&mut out);
+        out
+    }
+}
+
+// ── Tools ──────────────────────────────────────────────────────────────────
+
+/// `slop_ledger_append` — append one or more entries to the slop ledger.
+pub struct SlopLedgerAppendTool;
+
+#[async_trait]
+impl ToolSpec for SlopLedgerAppendTool {
+    fn name(&self) -> &'static str {
+        "slop_ledger_append"
+    }
+
+    fn description(&self) -> &'static str {
+        "Append one or more entries to the slop ledger — a durable record of \
+         unresolved architectural residue (compatibility shims, unmigrated \
+         callers, duplicate concepts, stale docs/tests, suspected dead code, \
+         tool gaps, etc.). Use this when you complete a task and notice \
+         residue that should be tracked for future cleanup. Each entry needs \
+         a bucket, severity, confidence, title, and description."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "entries": {
+                    "type": "array",
+                    "description": "One or more slop entries to append.",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "bucket": {
+                                "type": "string",
+                                "description": "One of: retained_compatibility, unmigrated_callers, duplicate_concepts, naming_drift, stale_docs, stale_tests, suspected_dead_code, unverified_public_behavior, tool_gaps, accepted_debt"
+                            },
+                            "severity": {
+                                "type": "string",
+                                "description": "critical | high | medium | low | info"
+                            },
+                            "confidence": {
+                                "type": "string",
+                                "description": "certain | high | medium | low"
+                            },
+                            "title": {
+                                "type": "string",
+                                "description": "Short title (one line)"
+                            },
+                            "description": {
+                                "type": "string",
+                                "description": "Detailed description of the residue"
+                            },
+                            "owner": {
+                                "type": "string",
+                                "description": "Optional: who should clean this up?"
+                            },
+                            "source_links": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Optional: file paths or URLs"
+                            }
+                        },
+                        "required": ["bucket", "severity", "confidence", "title", "description"]
+                    }
+                }
+            },
+            "required": ["entries"]
+        })
+    }
+
+    fn capabilities(&self) -> Vec<ToolCapability> {
+        vec![ToolCapability::WritesFiles]
+    }
+
+    fn approval_requirement(&self) -> ApprovalRequirement {
+        ApprovalRequirement::Auto
+    }
+
+    async fn execute(&self, input: Value, context: &ToolContext) -> Result<ToolResult, ToolError> {
+        let entries_val = input
+            .get("entries")
+            .and_then(|v| v.as_array())
+            .ok_or_else(|| ToolError::invalid_input("'entries' must be a non-empty array"))?;
+
+        let mut ledger = SlopLedger::load()
+            .map_err(|e| ToolError::execution_failed(format!("failed to load slop ledger: {e}")))?;
+
+        let mut appended = Vec::new();
+        for entry_val in entries_val {
+            let bucket_str = required_str(entry_val, "bucket")?;
+            let bucket = SlopBucket::from_str(bucket_str).ok_or_else(|| {
+                ToolError::invalid_input(format!("unknown bucket: '{bucket_str}'"))
+            })?;
+
+            let severity = SlopSeverity::from_str(required_str(entry_val, "severity")?)
+                .ok_or_else(|| {
+                    ToolError::invalid_input("invalid severity (use critical|high|medium|low|info)")
+                })?;
+
+            let confidence = SlopConfidence::from_str(required_str(entry_val, "confidence")?)
+                .ok_or_else(|| {
+                    ToolError::invalid_input("invalid confidence (use certain|high|medium|low)")
+                })?;
+
+            let title = required_str(entry_val, "title")?.to_string();
+            let description = required_str(entry_val, "description")?.to_string();
+
+            let mut entry = SlopEntry::new(bucket, severity, confidence, title, description);
+
+            if let Some(owner) = entry_val.get("owner").and_then(|v| v.as_str()) {
+                entry.owner = Some(owner.to_string());
+            }
+            if let Some(links) = entry_val.get("source_links").and_then(|v| v.as_array()) {
+                entry.source_links = links
+                    .iter()
+                    .filter_map(|v| v.as_str().map(String::from))
+                    .collect();
+            }
+
+            // Attach active task/thread context if available
+            if let Some(ref task_id) = context.runtime.active_task_id {
+                entry.task_id = Some(task_id.clone());
+            }
+            if let Some(ref thread_id) = context.runtime.active_thread_id {
+                entry.thread_id = Some(thread_id.clone());
+            }
+
+            appended.push(entry);
+        }
+
+        let (total, ids) = ledger.append(appended);
+        let appended_count = ids.len();
+
+        ledger
+            .save()
+            .map_err(|e| ToolError::execution_failed(format!("failed to save slop ledger: {e}")))?;
+
+        Ok(ToolResult::success(format!(
+            "Appended {} slop ledger entr{} ({} total): {}",
+            appended_count,
+            if appended_count == 1 { "y" } else { "ies" },
+            total,
+            ids.join(", ")
+        )))
+    }
+}
+
+/// `slop_ledger_query` — query the slop ledger.
+pub struct SlopLedgerQueryTool;
+
+#[async_trait]
+impl ToolSpec for SlopLedgerQueryTool {
+    fn name(&self) -> &'static str {
+        "slop_ledger_query"
+    }
+
+    fn description(&self) -> &'static str {
+        "Query the slop ledger for unresolved architectural residue. \
+         Filter by bucket, severity, status, or text search."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "bucket": {
+                    "type": "string",
+                    "description": "Optional: filter by bucket"
+                },
+                "severity": {
+                    "type": "string",
+                    "description": "Optional: filter by severity"
+                },
+                "status": {
+                    "type": "string",
+                    "description": "Optional: filter by status"
+                },
+                "search": {
+                    "type": "string",
+                    "description": "Optional: fuzzy text search in title and description"
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Optional: max results (default 50)"
+                }
+            }
+        })
+    }
+
+    fn capabilities(&self) -> Vec<ToolCapability> {
+        vec![]
+    }
+
+    fn approval_requirement(&self) -> ApprovalRequirement {
+        ApprovalRequirement::Auto
+    }
+
+    async fn execute(&self, input: Value, _context: &ToolContext) -> Result<ToolResult, ToolError> {
+        let filter = SlopLedgerFilter {
+            bucket: input
+                .get("bucket")
+                .and_then(|v| v.as_str())
+                .and_then(SlopBucket::from_str),
+            severity: input
+                .get("severity")
+                .and_then(|v| v.as_str())
+                .and_then(SlopSeverity::from_str),
+            status: input
+                .get("status")
+                .and_then(|v| v.as_str())
+                .and_then(SlopEntryStatus::from_str),
+            search: input
+                .get("search")
+                .and_then(|v| v.as_str())
+                .map(String::from),
+            limit: input
+                .get("limit")
+                .and_then(|v| v.as_u64())
+                .map(|n| n as usize)
+                .or(Some(50)),
+        };
+
+        let ledger = SlopLedger::load()
+            .map_err(|e| ToolError::execution_failed(format!("failed to load slop ledger: {e}")))?;
+
+        if ledger.is_empty() {
+            return Ok(ToolResult::success("Slop ledger is empty."));
+        }
+
+        let results = ledger.query(&filter);
+        let mut out = format!("Found {} matching slop ledger entries:\n\n", results.len());
+        for entry in &results {
+            out.push_str(&format!(
+                "- [{}] **{}** ({:?} | {:?} | {:?}) — {}\n",
+                short_id(&entry.id),
+                entry.bucket.as_str(),
+                entry.severity,
+                entry.confidence,
+                entry.status,
+                entry.title
+            ));
+            if let Some(ref desc) = entry.description.lines().next() {
+                out.push_str(&format!("  {desc}\n"));
+            }
+        }
+        Ok(ToolResult::success(out))
+    }
+}
+
+/// `slop_ledger_update` — update an entry's status.
+pub struct SlopLedgerUpdateTool;
+
+#[async_trait]
+impl ToolSpec for SlopLedgerUpdateTool {
+    fn name(&self) -> &'static str {
+        "slop_ledger_update"
+    }
+
+    fn description(&self) -> &'static str {
+        "Update a slop ledger entry's status (e.g., mark as resolved, accepted, or in-progress)."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "The entry ID (or prefix) to update"
+                },
+                "status": {
+                    "type": "string",
+                    "description": "New status: open | in_progress | resolved | accepted | wontfix"
+                },
+                "cleanup_recommendation": {
+                    "type": "string",
+                    "description": "Optional: cleanup notes when resolving or accepting"
+                }
+            },
+            "required": ["id", "status"]
+        })
+    }
+
+    fn capabilities(&self) -> Vec<ToolCapability> {
+        vec![ToolCapability::WritesFiles]
+    }
+
+    fn approval_requirement(&self) -> ApprovalRequirement {
+        ApprovalRequirement::Auto
+    }
+
+    async fn execute(&self, input: Value, _context: &ToolContext) -> Result<ToolResult, ToolError> {
+        let id = required_str(&input, "id")?;
+        let status =
+            SlopEntryStatus::from_str(required_str(&input, "status")?).ok_or_else(|| {
+                ToolError::invalid_input(
+                    "invalid status (use open|in_progress|resolved|accepted|wontfix)",
+                )
+            })?;
+
+        let cleanup = input
+            .get("cleanup_recommendation")
+            .and_then(|v| v.as_str())
+            .map(String::from);
+
+        let mut ledger = SlopLedger::load()
+            .map_err(|e| ToolError::execution_failed(format!("failed to load slop ledger: {e}")))?;
+
+        match ledger.update_status(id, status, cleanup) {
+            Ok(Some(entry)) => Ok(ToolResult::success(format!(
+                "Updated slop ledger entry {} ({}) → {:?}",
+                short_id(&entry.id),
+                entry.title,
+                entry.status
+            ))),
+            Ok(None) => Ok(ToolResult::success(format!(
+                "No slop ledger entry found matching '{id}'. Use slop_ledger_query to list entries."
+            ))),
+            Err(e) => Err(ToolError::execution_failed(format!(
+                "failed to update slop ledger: {e}"
+            ))),
+        }
+    }
+}
+
+/// `slop_ledger_export` — export ledger as Markdown.
+pub struct SlopLedgerExportTool;
+
+#[async_trait]
+impl ToolSpec for SlopLedgerExportTool {
+    fn name(&self) -> &'static str {
+        "slop_ledger_export"
+    }
+
+    fn description(&self) -> &'static str {
+        "Export the slop ledger as a Markdown report. Use this for handoffs, \
+         compaction relays, or GitHub issue creation. The output is suitable \
+         for pasting directly into a GitHub issue body."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "title": {
+                    "type": "string",
+                    "description": "Optional: report title (default 'Slop Ledger Export')"
+                },
+                "bucket": {
+                    "type": "string",
+                    "description": "Optional: filter by bucket"
+                },
+                "severity": {
+                    "type": "string",
+                    "description": "Optional: filter by severity"
+                },
+                "status": {
+                    "type": "string",
+                    "description": "Optional: filter by status"
+                }
+            }
+        })
+    }
+
+    fn capabilities(&self) -> Vec<ToolCapability> {
+        vec![]
+    }
+
+    fn approval_requirement(&self) -> ApprovalRequirement {
+        ApprovalRequirement::Auto
+    }
+
+    async fn execute(&self, input: Value, _context: &ToolContext) -> Result<ToolResult, ToolError> {
+        let title = input.get("title").and_then(|v| v.as_str());
+
+        let filter = if input.get("bucket").is_some()
+            || input.get("severity").is_some()
+            || input.get("status").is_some()
+        {
+            Some(SlopLedgerFilter {
+                bucket: input
+                    .get("bucket")
+                    .and_then(|v| v.as_str())
+                    .and_then(SlopBucket::from_str),
+                severity: input
+                    .get("severity")
+                    .and_then(|v| v.as_str())
+                    .and_then(SlopSeverity::from_str),
+                status: input
+                    .get("status")
+                    .and_then(|v| v.as_str())
+                    .and_then(SlopEntryStatus::from_str),
+                ..Default::default()
+            })
+        } else {
+            None
+        };
+
+        let ledger = SlopLedger::load()
+            .map_err(|e| ToolError::execution_failed(format!("failed to load slop ledger: {e}")))?;
+
+        let markdown = ledger.export_markdown(title, filter.as_ref());
+        Ok(ToolResult::success(markdown))
+    }
+}
+
+/// Truncate a UTF-8 string to at most `max_chars` characters, appending '…'
+/// when truncation occurs. Operates on char boundaries — never panics on
+/// multi-byte characters.
+fn truncate_str(s: &str, max_chars: usize) -> String {
+    if s.chars().count() <= max_chars {
+        return s.to_string();
+    }
+    let truncated: String = s.chars().take(max_chars.saturating_sub(1)).collect();
+    format!("{truncated}…")
+}
+
+/// Return a display-safe short id without assuming byte offsets are char
+/// boundaries. Ledger ids are normally UUIDs, but imported or hand-edited
+/// ledgers may contain shorter or non-ASCII ids.
+#[must_use]
+pub fn short_id(id: &str) -> String {
+    id.chars().take(8).collect()
+}
+
+/// Redact sensitive patterns from exported text: API keys and secrets
+/// paths. Scan the output for known key prefixes (`sk-`, `Bearer `, `dsk-`)
+/// and replace the token until a whitespace / punctuation boundary with
+/// `[REDACTED]`. Also normalises fully-qualified secrets directory paths
+/// to the portable `~/.codewhale/secrets` form.
+fn redact_exported_text(text: &mut String) {
+    let prefixes: &[&[u8]] = &[b"sk-", b"Bearer ", b"dsk-", b"deepseek-"];
+    let mut result = String::with_capacity(text.len());
+    let bytes = text.as_bytes();
+    let mut i = 0usize;
+    while i < bytes.len() {
+        let mut matched = false;
+        for prefix in prefixes {
+            if bytes[i..].len() >= prefix.len()
+                && bytes[i..i + prefix.len()].eq_ignore_ascii_case(prefix)
+            {
+                // Scan forward to first whitespace or delimiter.
+                let end = bytes[i + prefix.len()..]
+                    .iter()
+                    .position(|b| b.is_ascii_whitespace() || *b == b',' || *b == b';')
+                    .map(|p| i + prefix.len() + p)
+                    .unwrap_or(bytes.len());
+                result.push_str("[REDACTED]");
+                i = end;
+                matched = true;
+                break;
+            }
+        }
+        if !matched {
+            // Advance by one char (preserving multi-byte UTF-8 safety).
+            let ch = text[i..].chars().next().unwrap();
+            result.push(ch);
+            i += ch.len_utf8();
+        }
+    }
+
+    // Normalise secrets directory paths.
+    if let Some(home) = dirs::home_dir() {
+        for leaf in [".codewhale/secrets", ".deepseek/secrets"] {
+            let dir = home.join(leaf);
+            let prefix = dir.to_string_lossy().to_string();
+            result = result.replace(&prefix, "~/.codewhale/secrets");
+        }
+    }
+    *text = result;
+}
+
+impl SlopLedger {
+    /// Completion-gate / verifier hook: returns `true` when there are
+    /// unresolved slop entries (status `Open` or `InProgress`) that the
+    /// agent should review before claiming the task is done.
+    ///
+    /// Tools and engine hooks can call this on claim-of-done to surface
+    /// architectural residue the agent may have overlooked.
+    #[allow(dead_code)]
+    #[must_use]
+    pub fn has_open_entries(&self) -> bool {
+        self.entries.iter().any(|e| {
+            matches!(
+                e.status,
+                SlopEntryStatus::Open | SlopEntryStatus::InProgress
+            )
+        })
+    }
+
+    /// Return a concise completion-gate summary suitable for a verifier
+    /// sub-agent or the claim-of-done prompt. Returns `None` when all
+    /// entries are resolved — the caller can then treat the gate as "pass".
+    #[allow(dead_code)]
+    #[must_use]
+    pub fn completion_gate_summary(&self) -> Option<String> {
+        let open: Vec<&SlopEntry> = self
+            .entries
+            .iter()
+            .filter(|e| {
+                matches!(
+                    e.status,
+                    SlopEntryStatus::Open | SlopEntryStatus::InProgress
+                )
+            })
+            .collect();
+        if open.is_empty() {
+            return None;
+        }
+        let mut out = format!(
+            "## ⚠️ SlopLedger gate — {} open slop entries\n\n",
+            open.len()
+        );
+        out.push_str("Review these before claiming completion:\n\n");
+        for e in open {
+            out.push_str(&format!(
+                "- **{}** `{}` ({:?}/{:?}): {}\n",
+                e.bucket.as_str(),
+                short_id(&e.id),
+                e.severity,
+                e.confidence,
+                truncate_str(&e.title, 80),
+            ));
+        }
+        Some(out)
+    }
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn temp_ledger() -> (TempDir, SlopLedger) {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join("slop_ledger.json");
+        let ledger = SlopLedger {
+            entries: Vec::new(),
+            ledger_path: path,
+        };
+        (tmp, ledger)
+    }
+
+    #[test]
+    fn bucket_roundtrip() {
+        for bucket in SlopBucket::all_buckets() {
+            let s = bucket.as_str();
+            let parsed = SlopBucket::from_str(s);
+            assert_eq!(parsed, Some(*bucket), "roundtrip failed for {s}");
+        }
+    }
+
+    #[test]
+    fn append_and_save_load() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let entry = SlopEntry::new(
+            SlopBucket::StaleDocs,
+            SlopSeverity::Medium,
+            SlopConfidence::High,
+            "README is outdated".into(),
+            "The README still references v0.7 APIs.".into(),
+        );
+
+        let _ = ledger.append(vec![entry]);
+        assert_eq!(ledger.len(), 1);
+        ledger.save().unwrap();
+
+        let loaded = SlopLedger::load_at(&ledger.ledger_path).unwrap();
+        assert_eq!(loaded.len(), 1);
+        assert_eq!(loaded.entries[0].title, "README is outdated");
+    }
+
+    #[test]
+    fn short_id_handles_short_and_non_ascii_ids() {
+        assert_eq!(short_id("abc"), "abc");
+        assert_eq!(short_id("abcdefghi"), "abcdefgh");
+        assert_eq!(short_id("残渣-ledger-entry"), "残渣-ledge");
+    }
+
+    #[test]
+    fn display_paths_do_not_panic_on_short_or_non_ascii_ids() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let mut short = SlopEntry::new(
+            SlopBucket::StaleDocs,
+            SlopSeverity::Low,
+            SlopConfidence::High,
+            "short id".into(),
+            "desc".into(),
+        );
+        short.id = "abc".into();
+
+        let mut unicode = SlopEntry::new(
+            SlopBucket::ToolGaps,
+            SlopSeverity::Medium,
+            SlopConfidence::Medium,
+            "unicode id".into(),
+            "desc".into(),
+        );
+        unicode.id = "残渣-ledger-entry".into();
+
+        let (_total, ids) = ledger.append(vec![short, unicode]);
+        assert_eq!(ids, vec!["abc", "残渣-ledge"]);
+
+        let md = ledger.export_markdown(None, None);
+        assert!(md.contains("| abc |"));
+        assert!(md.contains("| 残渣-ledge |"));
+        assert!(ledger.completion_gate_summary().is_some());
+    }
+
+    #[test]
+    fn query_by_bucket() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let _ = ledger.append(vec![
+            SlopEntry::new(
+                SlopBucket::StaleDocs,
+                SlopSeverity::Low,
+                SlopConfidence::Certain,
+                "doc A".into(),
+                "desc A".into(),
+            ),
+            SlopEntry::new(
+                SlopBucket::ToolGaps,
+                SlopSeverity::High,
+                SlopConfidence::Medium,
+                "gap B".into(),
+                "desc B".into(),
+            ),
+        ]);
+
+        let filter = SlopLedgerFilter {
+            bucket: Some(SlopBucket::StaleDocs),
+            ..Default::default()
+        };
+        let results = ledger.query(&filter);
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].title, "doc A");
+    }
+
+    #[test]
+    fn query_by_search() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let _ = ledger.append(vec![SlopEntry::new(
+            SlopBucket::SuspectedDeadCode,
+            SlopSeverity::Medium,
+            SlopConfidence::Low,
+            "dead legacy handler".into(),
+            "The legacy handler in src/old.rs appears unused.".into(),
+        )]);
+
+        let filter = SlopLedgerFilter {
+            search: Some("legacy".into()),
+            ..Default::default()
+        };
+        let results = ledger.query(&filter);
+        assert_eq!(results.len(), 1);
+    }
+
+    #[test]
+    fn update_status() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let entry = SlopEntry::new(
+            SlopBucket::NamingDrift,
+            SlopSeverity::Low,
+            SlopConfidence::High,
+            "naming issue".into(),
+            "desc".into(),
+        );
+        let id = entry.id.clone();
+        let _ = ledger.append(vec![entry]);
+        ledger.save().unwrap();
+
+        let result = ledger
+            .update_status(
+                &id,
+                SlopEntryStatus::Resolved,
+                Some("Renamed in #1234".into()),
+            )
+            .unwrap();
+        assert!(result.is_some());
+
+        let loaded = SlopLedger::load_at(&ledger.ledger_path).unwrap();
+        assert_eq!(loaded.entries[0].status, SlopEntryStatus::Resolved);
+        assert_eq!(
+            loaded.entries[0].cleanup_recommendation,
+            Some("Renamed in #1234".into())
+        );
+    }
+
+    #[test]
+    fn update_status_returns_entry_for_prefix_match() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let entry = SlopEntry::new(
+            SlopBucket::NamingDrift,
+            SlopSeverity::Low,
+            SlopConfidence::High,
+            "naming issue".into(),
+            "desc".into(),
+        );
+        let id = entry.id.clone();
+        let prefix = short_id(&id);
+        let _ = ledger.append(vec![entry]);
+        ledger.save().unwrap();
+
+        let result = ledger
+            .update_status(&prefix, SlopEntryStatus::Resolved, None)
+            .unwrap();
+
+        assert_eq!(result.map(|entry| entry.id.as_str()), Some(id.as_str()));
+    }
+
+    #[test]
+    fn export_markdown() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let mut entry = SlopEntry::new(
+            SlopBucket::StaleDocs,
+            SlopSeverity::Medium,
+            SlopConfidence::High,
+            "Outdated README".into(),
+            "The README references removed flags.".into(),
+        );
+        entry.source_links = vec!["README.md:42".into()];
+        let _ = ledger.append(vec![entry]);
+
+        let md = ledger.export_markdown(Some("Test Export"), None);
+        assert!(md.contains("Test Export"));
+        assert!(md.contains("stale_docs"));
+        assert!(md.contains("Outdated README"));
+        assert!(md.contains("README.md:42"));
+    }
+
+    #[test]
+    fn empty_ledger_loads() {
+        let (_tmp, ledger) = temp_ledger();
+        assert!(ledger.is_empty());
+        assert_eq!(ledger.len(), 0);
+    }
+
+    #[test]
+    fn summary_counts() {
+        let (_tmp, mut ledger) = temp_ledger();
+
+        let mut e1 = SlopEntry::new(
+            SlopBucket::StaleDocs,
+            SlopSeverity::Medium,
+            SlopConfidence::High,
+            "doc".into(),
+            "desc".into(),
+        );
+        e1.status = SlopEntryStatus::Open;
+
+        let mut e2 = SlopEntry::new(
+            SlopBucket::ToolGaps,
+            SlopSeverity::High,
+            SlopConfidence::Certain,
+            "gap".into(),
+            "desc".into(),
+        );
+        e2.status = SlopEntryStatus::Resolved;
+
+        let mut e3 = SlopEntry::new(
+            SlopBucket::AcceptedDebt,
+            SlopSeverity::Low,
+            SlopConfidence::Medium,
+            "debt".into(),
+            "desc".into(),
+        );
+        e3.status = SlopEntryStatus::Accepted;
+
+        let _ = ledger.append(vec![e1, e2, e3]);
+
+        let summary = ledger.summary();
+        assert!(summary.contains("3 total"));
+        assert!(summary.contains("stale_docs: 1"));
+        assert!(summary.contains("tool_gaps: 1"));
+        assert!(summary.contains("accepted_debt: 1"));
+    }
+}
diff --git a/crates/tui/src/snapshot/paths.rs b/crates/tui/src/snapshot/paths.rs
index 90d70091..d1ac8c78 100644
--- a/crates/tui/src/snapshot/paths.rs
+++ b/crates/tui/src/snapshot/paths.rs
@@ -1,18 +1,20 @@
 //! Path resolution for the per-workspace snapshot side-repos.
 //!
-//! Snapshots live in `~/.deepseek/snapshots/<project_hash>/<worktree_hash>/`.
-//! The two-level hash split lets us snapshot multiple worktrees of the same
-//! project independently — `git worktree list` users won't get cross-talk
-//! between feature branches.
+//! Snapshots live under the resolved state directory
+//! (`~/.codewhale/snapshots` or legacy `~/.deepseek/snapshots`) with
+//! a two-level hash split so we can snapshot multiple worktrees of the
+//! same project independently — `git worktree list` users won't get
+//! cross-talk between feature branches.
 
 use std::io;
 use std::path::{Path, PathBuf};
 
 /// Compute the snapshot directory for a given workspace path.
 ///
-/// Returns `~/.deepseek/snapshots/<project_hash>/<worktree_hash>/`. The
-/// caller is responsible for creating it on disk; we purposefully don't
-/// touch the filesystem here so this is cheap to call repeatedly.
+/// Returns `$STATE_DIR/snapshots/<project_hash>/<worktree_hash>/` where
+/// `$STATE_DIR` is resolved via `codewhale_config::resolve_state_dir`.
+/// The caller is responsible for creating it on disk; we purposefully
+/// don't touch the filesystem here so this is cheap to call repeatedly.
 ///
 /// The `project_hash` is derived from the canonicalized workspace path
 /// after stripping any `.worktrees/<name>` suffix — multiple worktrees
@@ -24,7 +26,7 @@ pub fn snapshot_dir_for(workspace: &Path) -> PathBuf {
 }
 
 /// Same as [`snapshot_dir_for`] but with an injectable home directory.
-/// Used by tests so we never touch the user's real `~/.deepseek/`.
+/// Used by tests so they never touch the user's real state directory.
 pub fn snapshot_dir_with_home(workspace: &Path, home: Option<PathBuf>) -> PathBuf {
     let home = home.unwrap_or_else(|| PathBuf::from("."));
     let canonical = workspace
@@ -33,12 +35,21 @@ pub fn snapshot_dir_with_home(workspace: &Path, home: Option<PathBuf>) -> PathBu
     let project_root = strip_worktree_suffix(&canonical);
     let project_hash = stable_hex(&project_root);
     let worktree_hash = stable_hex(&canonical);
-    home.join(".deepseek")
-        .join("snapshots")
+    snapshot_base_with_home(Some(home))
         .join(project_hash)
         .join(worktree_hash)
 }
 
+fn snapshot_base_with_home(home: Option<PathBuf>) -> PathBuf {
+    let home = home.unwrap_or_else(|| PathBuf::from("."));
+    // Prefer .codewhale, fall back to .deepseek
+    let primary = home.join(".codewhale").join("snapshots");
+    if primary.exists() {
+        return primary;
+    }
+    home.join(".deepseek").join("snapshots")
+}
+
 /// Resolve the `.git` directory inside the snapshot dir.
 pub fn snapshot_git_dir(workspace: &Path) -> PathBuf {
     snapshot_dir_for(workspace).join(".git")
diff --git a/crates/tui/src/task_manager.rs b/crates/tui/src/task_manager.rs
index b0d9e39e..8f927023 100644
--- a/crates/tui/src/task_manager.rs
+++ b/crates/tui/src/task_manager.rs
@@ -1648,9 +1648,9 @@ pub fn default_tasks_dir() -> PathBuf {
         return PathBuf::from(path);
     }
     if let Some(home) = dirs::home_dir() {
-        return home.join(".deepseek").join("tasks");
+        return home.join(".codewhale").join("tasks");
     }
-    PathBuf::from(".deepseek").join("tasks")
+    PathBuf::from(".codewhale").join("tasks")
 }
 
 /// Wait for a task to reach a terminal status (tests and API helpers).
diff --git a/crates/tui/src/theme_qa_audit.rs b/crates/tui/src/theme_qa_audit.rs
new file mode 100644
index 00000000..37c1435a
--- /dev/null
+++ b/crates/tui/src/theme_qa_audit.rs
@@ -0,0 +1,326 @@
+//! v0.8.45 theme QA audit — verification script.
+//!
+//! This module validates:
+//! - Every shipped theme has all required semantic palette fields populated.
+//! - Error/destructive states are distinct from warm action accents.
+//! - Selection, focus, diff, warning, success, and status colors are readable.
+//! - Terminal contrast is checked for common truecolor surfaces.
+//!
+//! Run with: cargo test -p codewhale-tui -- theme_qa
+
+#[cfg(test)]
+mod tests {
+    use crate::palette::{
+        CATPPUCCIN_MOCHA_UI_THEME, DRACULA_UI_THEME, GRAYSCALE_UI_THEME, GRUVBOX_DARK_UI_THEME,
+        LIGHT_UI_THEME, TOKYO_NIGHT_UI_THEME, UI_THEME, UiTheme, WHALE_ACCENT_ACTION_RGB,
+        WHALE_ACCENT_PRIMARY_RGB, WHALE_ACCENT_SECONDARY_RGB, WHALE_BG_RGB, WHALE_TEXT_BODY_RGB,
+        WHALE_TEXT_MUTED_RGB,
+    };
+    use ratatui::style::Color;
+
+    /// All shipped themes in display order.
+    const ALL_THEMES: &[UiTheme] = &[
+        UI_THEME,
+        LIGHT_UI_THEME,
+        GRAYSCALE_UI_THEME,
+        CATPPUCCIN_MOCHA_UI_THEME,
+        TOKYO_NIGHT_UI_THEME,
+        DRACULA_UI_THEME,
+        GRUVBOX_DARK_UI_THEME,
+    ];
+
+    /// Extract (r, g, b) from a Color::Rgb. Returns None for non-RGB colors.
+    fn rgb(color: Color) -> Option<(u8, u8, u8)> {
+        match color {
+            Color::Rgb(r, g, b) => Some((r, g, b)),
+            _ => None,
+        }
+    }
+
+    /// Relative luminance per WCAG 2.1.
+    fn relative_luminance(r: u8, g: u8, b: u8) -> f64 {
+        fn channel(c: u8) -> f64 {
+            let s = c as f64 / 255.0;
+            if s <= 0.03928 {
+                s / 12.92
+            } else {
+                ((s + 0.055) / 1.055).powf(2.4)
+            }
+        }
+        0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
+    }
+
+    /// WCAG 2.1 contrast ratio.
+    fn contrast_ratio(fg: (u8, u8, u8), bg: (u8, u8, u8)) -> f64 {
+        let l1 = relative_luminance(fg.0, fg.1, fg.2);
+        let l2 = relative_luminance(bg.0, bg.1, bg.2);
+        let (lighter, darker) = if l1 > l2 { (l1, l2) } else { (l2, l1) };
+        (lighter + 0.05) / (darker + 0.05)
+    }
+
+    #[test]
+    fn all_themes_have_non_default_surface_bg() {
+        for theme in ALL_THEMES {
+            assert!(
+                rgb(theme.surface_bg).is_some(),
+                "{}: surface_bg must be an RGB color",
+                theme.name
+            );
+        }
+    }
+
+    #[test]
+    fn all_themes_have_required_semantic_fields() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            // Every theme must have distinct accent colors.
+            assert!(
+                rgb(theme.accent_primary).is_some(),
+                "{name}: accent_primary missing"
+            );
+            assert!(
+                rgb(theme.accent_secondary).is_some(),
+                "{name}: accent_secondary missing"
+            );
+            assert!(
+                rgb(theme.accent_action).is_some(),
+                "{name}: accent_action missing"
+            );
+
+            // Error/destructive must be separate from action accent.
+            assert_ne!(
+                theme.error_fg, theme.accent_action,
+                "{name}: error_fg should differ from accent_action"
+            );
+            assert_ne!(
+                theme.error_fg, theme.accent_primary,
+                "{name}: error_fg should differ from accent_primary"
+            );
+
+            // Error fields present.
+            assert!(rgb(theme.error_fg).is_some(), "{name}: error_fg missing");
+            assert!(
+                rgb(theme.error_hover).is_some(),
+                "{name}: error_hover missing"
+            );
+            assert!(
+                rgb(theme.error_surface).is_some(),
+                "{name}: error_surface missing"
+            );
+            assert!(
+                rgb(theme.error_border).is_some(),
+                "{name}: error_border missing"
+            );
+            assert!(
+                rgb(theme.error_text).is_some(),
+                "{name}: error_text missing"
+            );
+
+            // Warning / success / info present.
+            assert!(rgb(theme.warning).is_some(), "{name}: warning missing");
+            assert!(rgb(theme.success).is_some(), "{name}: success missing");
+            assert!(rgb(theme.info).is_some(), "{name}: info missing");
+
+            // Diff colors present.
+            assert!(
+                rgb(theme.diff_added_fg).is_some(),
+                "{name}: diff_added_fg missing"
+            );
+            assert!(
+                rgb(theme.diff_deleted_fg).is_some(),
+                "{name}: diff_deleted_fg missing"
+            );
+            assert!(
+                rgb(theme.diff_added_bg).is_some(),
+                "{name}: diff_added_bg missing"
+            );
+            assert!(
+                rgb(theme.diff_deleted_bg).is_some(),
+                "{name}: diff_deleted_bg missing"
+            );
+
+            // Tool colors present.
+            assert!(
+                rgb(theme.tool_running).is_some(),
+                "{name}: tool_running missing"
+            );
+            assert!(
+                rgb(theme.tool_success).is_some(),
+                "{name}: tool_success missing"
+            );
+            assert!(
+                rgb(theme.tool_failed).is_some(),
+                "{name}: tool_failed missing"
+            );
+        }
+    }
+
+    #[test]
+    fn body_text_has_minimum_contrast_on_surface() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            let Some(fg) = rgb(theme.text_body) else {
+                continue;
+            };
+            let Some(bg) = rgb(theme.surface_bg) else {
+                continue;
+            };
+            let cr = contrast_ratio(fg, bg);
+            assert!(
+                cr >= 4.5,
+                "{name}: body text contrast {cr:.1}:1 is below 4.5:1 minimum (fg={fg:?}, bg={bg:?})"
+            );
+        }
+    }
+
+    #[test]
+    fn muted_text_is_readable_on_surface() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            let Some(fg) = rgb(theme.text_muted) else {
+                continue;
+            };
+            let Some(bg) = rgb(theme.surface_bg) else {
+                continue;
+            };
+            let cr = contrast_ratio(fg, bg);
+            assert!(
+                cr >= 3.0,
+                "{name}: muted text contrast {cr:.1}:1 is below 3.0:1 minimum (fg={fg:?}, bg={bg:?})"
+            );
+        }
+    }
+
+    #[test]
+    fn error_text_contrasts_on_error_surface() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            let Some(fg) = rgb(theme.error_text) else {
+                continue;
+            };
+            let Some(bg) = rgb(theme.error_surface) else {
+                continue;
+            };
+            let cr = contrast_ratio(fg, bg);
+            assert!(
+                cr >= 4.5,
+                "{name}: error_text on error_surface contrast {cr:.1}:1 is below 4.5:1"
+            );
+        }
+    }
+
+    #[test]
+    fn selection_bg_differs_from_surface_bg() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            assert_ne!(
+                theme.selection_bg, theme.surface_bg,
+                "{name}: selection_bg must differ from surface_bg"
+            );
+        }
+    }
+
+    #[test]
+    fn surface_layers_are_distinct() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            // Panel should be distinct from surface (unless grayscale which has limited range).
+            if theme.name != "grayscale" {
+                assert_ne!(
+                    theme.panel_bg, theme.surface_bg,
+                    "{name}: panel_bg must differ from surface_bg for visual layering"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn success_and_warning_are_visually_distinct() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            assert_ne!(
+                theme.success, theme.warning,
+                "{name}: success and warning must be distinct colors"
+            );
+            assert_ne!(
+                theme.success, theme.error_fg,
+                "{name}: success and error must be distinct colors"
+            );
+        }
+    }
+
+    #[test]
+    fn diff_added_and_deleted_are_distinct() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            assert_ne!(
+                theme.diff_added_fg, theme.diff_deleted_fg,
+                "{name}: diff add/del fg must differ"
+            );
+            assert_ne!(
+                theme.diff_added_bg, theme.diff_deleted_bg,
+                "{name}: diff add/del bg must differ"
+            );
+        }
+    }
+
+    #[test]
+    fn mode_colors_are_all_distinct() {
+        for theme in ALL_THEMES {
+            let name = theme.name;
+            let modes = [
+                ("agent", theme.mode_agent),
+                ("yolo", theme.mode_yolo),
+                ("plan", theme.mode_plan),
+                ("goal", theme.mode_goal),
+            ];
+            for i in 0..modes.len() {
+                for j in (i + 1)..modes.len() {
+                    assert_ne!(
+                        modes[i].1, modes[j].1,
+                        "{name}: mode {} and mode {} have same color",
+                        modes[i].0, modes[j].0
+                    );
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn whale_dark_uses_proposed_palette() {
+        // Issue #2012: verify the default Whale dark uses proposed tokens.
+        let t = UI_THEME;
+        assert_eq!(rgb(t.surface_bg), Some(WHALE_BG_RGB), "Deep Navy #0A1120");
+        assert_eq!(
+            rgb(t.text_body),
+            Some(WHALE_TEXT_BODY_RGB),
+            "Whale Ivory #F6F2E8"
+        );
+        assert_eq!(
+            rgb(t.text_muted),
+            Some(WHALE_TEXT_MUTED_RGB),
+            "Mist Gray #A9B4C7"
+        );
+        assert_eq!(
+            rgb(t.accent_primary),
+            Some(WHALE_ACCENT_PRIMARY_RGB),
+            "Signal Gold #F6C453"
+        );
+        assert_eq!(
+            rgb(t.accent_secondary),
+            Some(WHALE_ACCENT_SECONDARY_RGB),
+            "Seafoam #4FD1C5"
+        );
+        assert_eq!(
+            rgb(t.accent_action),
+            Some(WHALE_ACCENT_ACTION_RGB),
+            "Coral Spark #FF7A59"
+        );
+        assert_eq!(rgb(t.error_fg), Some((255, 92, 122)), "Rose Red #FF5C7A");
+        assert_eq!(
+            rgb(t.error_surface),
+            Some((42, 18, 26)),
+            "Error Surface #2A121A"
+        );
+    }
+}
diff --git a/crates/tui/src/tool_output_receipts.rs b/crates/tui/src/tool_output_receipts.rs
new file mode 100644
index 00000000..715255a8
--- /dev/null
+++ b/crates/tui/src/tool_output_receipts.rs
@@ -0,0 +1,507 @@
+//! Compact receipts for oversized tool outputs in saved session history.
+
+use std::collections::HashMap;
+
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+
+use crate::artifacts::{ArtifactKind, ArtifactRecord, format_artifact_relative_path};
+use crate::models::{ContentBlock, Message};
+use crate::tools::truncate;
+
+/// Match the provider-wire budget so persisted/resumed history does not keep a
+/// larger raw body than the model would receive on a fresh request.
+pub const RAW_TOOL_OUTPUT_RECEIPT_THRESHOLD_CHARS: usize = 12_000;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ToolOutputReceiptStats {
+    pub compacted_count: usize,
+    pub artifact_receipts: usize,
+    pub sha_receipts: usize,
+    pub unavailable_receipts: usize,
+    pub original_chars: usize,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ToolOutputStatus {
+    pub raw_large_count: usize,
+    pub raw_large_chars: usize,
+    pub receipt_count: usize,
+    pub artifact_count: usize,
+    pub artifact_bytes: u64,
+}
+
+#[derive(Debug, Clone)]
+struct ToolUseInfo {
+    name: String,
+    input: Value,
+}
+
+#[derive(Debug, Clone)]
+enum DetailHandle {
+    Artifact(ArtifactRecord),
+    Sha { sha: String, persisted: bool },
+}
+
+/// Return a copy of `messages` with oversized raw tool-result bodies replaced
+/// by compact receipts. Full output is kept behind existing session artifacts
+/// when available; otherwise a SHA-addressed spillover copy is written for
+/// `retrieve_tool_result`.
+pub fn compact_messages_for_persistence(
+    messages: &[Message],
+    artifacts: &[ArtifactRecord],
+) -> (Vec<Message>, ToolOutputReceiptStats) {
+    let artifacts_by_call = artifacts_by_tool_call(artifacts);
+    let mut tool_uses: HashMap<String, ToolUseInfo> = HashMap::new();
+    let mut stats = ToolOutputReceiptStats::default();
+    let mut compacted = Vec::with_capacity(messages.len());
+
+    for message in messages {
+        let mut next = message.clone();
+        for block in &mut next.content {
+            match block {
+                ContentBlock::ToolUse {
+                    id, name, input, ..
+                } => {
+                    tool_uses.insert(
+                        id.clone(),
+                        ToolUseInfo {
+                            name: name.clone(),
+                            input: input.clone(),
+                        },
+                    );
+                }
+                ContentBlock::ToolResult {
+                    tool_use_id,
+                    content,
+                    is_error,
+                    ..
+                } => {
+                    let char_count = content.chars().count();
+                    if char_count <= RAW_TOOL_OUTPUT_RECEIPT_THRESHOLD_CHARS
+                        || looks_like_receipt(content)
+                    {
+                        continue;
+                    }
+
+                    let tool_info = tool_uses.get(tool_use_id);
+                    let handle = artifacts_by_call
+                        .get(tool_use_id.as_str())
+                        .cloned()
+                        .map(|artifact| DetailHandle::Artifact((*artifact).clone()))
+                        .unwrap_or_else(|| DetailHandle::Sha {
+                            sha: sha256_hex(content.as_bytes()),
+                            persisted: persist_sha_tool_result(content),
+                        });
+                    let source = match &handle {
+                        DetailHandle::Artifact(_) => ReceiptSource::Artifact,
+                        DetailHandle::Sha {
+                            persisted: true, ..
+                        } => ReceiptSource::Sha,
+                        DetailHandle::Sha {
+                            persisted: false, ..
+                        } => ReceiptSource::Unavailable,
+                    };
+
+                    *content = render_tool_output_receipt(
+                        tool_use_id,
+                        tool_info,
+                        content,
+                        *is_error,
+                        &handle,
+                    );
+                    stats.compacted_count += 1;
+                    stats.original_chars = stats.original_chars.saturating_add(char_count);
+                    match source {
+                        ReceiptSource::Artifact => stats.artifact_receipts += 1,
+                        ReceiptSource::Sha => stats.sha_receipts += 1,
+                        ReceiptSource::Unavailable => stats.unavailable_receipts += 1,
+                    }
+                }
+                _ => {}
+            }
+        }
+        compacted.push(next);
+    }
+
+    (compacted, stats)
+}
+
+pub fn tool_output_status(messages: &[Message], artifacts: &[ArtifactRecord]) -> ToolOutputStatus {
+    let mut status = ToolOutputStatus {
+        artifact_count: artifacts.len(),
+        artifact_bytes: artifacts
+            .iter()
+            .map(|artifact| artifact.byte_size)
+            .sum::<u64>(),
+        ..ToolOutputStatus::default()
+    };
+
+    for message in messages {
+        for block in &message.content {
+            if let ContentBlock::ToolResult { content, .. } = block {
+                if looks_like_receipt(content) {
+                    status.receipt_count += 1;
+                } else {
+                    let chars = content.chars().count();
+                    if chars > RAW_TOOL_OUTPUT_RECEIPT_THRESHOLD_CHARS {
+                        status.raw_large_count += 1;
+                        status.raw_large_chars = status.raw_large_chars.saturating_add(chars);
+                    }
+                }
+            }
+        }
+    }
+
+    status
+}
+
+pub fn format_tool_output_status(status: &ToolOutputStatus) -> String {
+    let mut parts = Vec::new();
+    if status.raw_large_count > 0 {
+        parts.push(format!(
+            "{} raw over cap (~{} chars) adding context pressure",
+            status.raw_large_count,
+            format_count(status.raw_large_chars)
+        ));
+    }
+    if status.receipt_count > 0 {
+        parts.push(format!("{} compact receipt(s)", status.receipt_count));
+    }
+    if status.artifact_count > 0 {
+        parts.push(format!(
+            "{} artifact(s), {} stored",
+            status.artifact_count,
+            crate::artifacts::format_byte_size(status.artifact_bytes)
+        ));
+    }
+    if parts.is_empty() {
+        "no large outputs tracked".to_string()
+    } else {
+        parts.join("; ")
+    }
+}
+
+fn artifacts_by_tool_call(artifacts: &[ArtifactRecord]) -> HashMap<&str, &ArtifactRecord> {
+    artifacts
+        .iter()
+        .filter(|artifact| artifact.kind == ArtifactKind::ToolOutput)
+        .map(|artifact| (artifact.tool_call_id.as_str(), artifact))
+        .collect()
+}
+
+#[derive(Debug, Clone, Copy)]
+enum ReceiptSource {
+    Artifact,
+    Sha,
+    Unavailable,
+}
+
+fn render_tool_output_receipt(
+    tool_call_id: &str,
+    tool_info: Option<&ToolUseInfo>,
+    original_content: &str,
+    is_error: Option<bool>,
+    handle: &DetailHandle,
+) -> String {
+    let original_chars = original_content.chars().count();
+    let original_bytes = original_content.len() as u64;
+    let tool_name = match handle {
+        DetailHandle::Artifact(record) if !record.tool_name.trim().is_empty() => {
+            record.tool_name.as_str()
+        }
+        _ => tool_info
+            .map(|info| info.name.as_str())
+            .filter(|name| !name.trim().is_empty())
+            .unwrap_or("unknown"),
+    };
+    let command_or_query = tool_info
+        .map(|info| summarize_input(&info.input, 300))
+        .unwrap_or_else(|| "unknown".to_string());
+    let status = if is_error.unwrap_or(false) {
+        "error"
+    } else {
+        "success"
+    };
+    let exit_status = infer_exit_status(original_content).unwrap_or_else(|| "unknown".to_string());
+    let preview = preview_for_receipt(handle, original_content);
+    let (detail_handle, retrieve, storage) = match handle {
+        DetailHandle::Artifact(record) => (
+            record.id.clone(),
+            format!("retrieve_tool_result ref={}", record.id),
+            format_artifact_relative_path(&record.storage_path),
+        ),
+        DetailHandle::Sha { sha, persisted } => {
+            let handle = format!("sha:{sha}");
+            let storage = if *persisted {
+                "content-addressed spillover".to_string()
+            } else {
+                "unavailable; spillover write failed".to_string()
+            };
+            (
+                handle.clone(),
+                format!("retrieve_tool_result ref={handle}"),
+                storage,
+            )
+        }
+    };
+
+    format!(
+        "[TOOL_OUTPUT_RECEIPT]\n\
+         tool: {tool_name}\n\
+         tool_call_id: {tool_call_id}\n\
+         status: {status}\n\
+         exit_status: {exit_status}\n\
+         elapsed: unknown\n\
+         output: {bytes} ({chars} chars, ~{tokens} tokens)\n\
+         truncation: raw output omitted from saved/resumed context\n\
+         detail_handle: {detail_handle}\n\
+         retrieve: {retrieve}\n\
+         storage: {storage}\n\
+         command_or_query: {command_or_query}\n\
+         preview: {preview}\n\
+         [/TOOL_OUTPUT_RECEIPT]",
+        bytes = crate::artifacts::format_byte_size(original_bytes),
+        chars = format_count(original_chars),
+        tokens = format_count(approx_tokens(original_chars)),
+    )
+}
+
+fn persist_sha_tool_result(content: &str) -> bool {
+    let sha = sha256_hex(content.as_bytes());
+    match truncate::write_sha_spillover(&sha, content) {
+        Ok(_) => true,
+        Err(err) => {
+            crate::logging::warn(format!(
+                "tool-output receipt SHA spillover write failed for sha={sha}: {err}"
+            ));
+            false
+        }
+    }
+}
+
+fn preview_for_receipt(handle: &DetailHandle, original_content: &str) -> String {
+    let preview = match handle {
+        DetailHandle::Artifact(record) if !record.preview.trim().is_empty() => {
+            record.preview.as_str()
+        }
+        _ => original_content,
+    };
+    summarize_text(preview, 240)
+}
+
+fn looks_like_receipt(content: &str) -> bool {
+    let trimmed = content.trim_start();
+    trimmed.starts_with("[TOOL_OUTPUT_RECEIPT]")
+        || trimmed.starts_with("[artifact:")
+        || trimmed.starts_with("[TOOL_RESULT_TRUNCATED]")
+        || trimmed.starts_with("<TOOL_RESULT_REF")
+}
+
+fn infer_exit_status(content: &str) -> Option<String> {
+    if let Ok(value) = serde_json::from_str::<Value>(content) {
+        for key in ["exit_code", "exit_status", "status", "code"] {
+            if let Some(value) = value.get(key) {
+                return Some(summarize_input(value, 120));
+            }
+        }
+    }
+
+    for line in content.lines().take(40) {
+        let trimmed = line.trim();
+        for prefix in ["Exit code:", "exit code:", "Exit status:", "exit status:"] {
+            if let Some(value) = trimmed.strip_prefix(prefix) {
+                return Some(summarize_text(value.trim(), 120));
+            }
+        }
+    }
+    None
+}
+
+fn summarize_input(value: &Value, max_chars: usize) -> String {
+    let raw = value
+        .as_str()
+        .map(str::to_string)
+        .unwrap_or_else(|| value.to_string());
+    summarize_text(&raw, max_chars)
+}
+
+fn summarize_text(text: &str, max_chars: usize) -> String {
+    let escaped = text.replace('\n', "\\n");
+    let mut summary: String = escaped.chars().take(max_chars).collect();
+    if escaped.chars().count() > max_chars {
+        summary.push_str("...");
+    }
+    summary
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(bytes);
+    format!("{:x}", hasher.finalize())
+}
+
+fn approx_tokens(chars: usize) -> usize {
+    chars.div_ceil(4)
+}
+
+fn format_count(value: usize) -> String {
+    value.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::{Path, PathBuf};
+
+    use chrono::Utc;
+    use serde_json::json;
+    use tempfile::tempdir;
+
+    use super::*;
+
+    fn tool_use_message(id: &str, name: &str, input: Value) -> Message {
+        Message {
+            role: "assistant".to_string(),
+            content: vec![ContentBlock::ToolUse {
+                id: id.to_string(),
+                name: name.to_string(),
+                input,
+                caller: None,
+            }],
+        }
+    }
+
+    fn tool_result_message(id: &str, content: &str) -> Message {
+        Message {
+            role: "user".to_string(),
+            content: vec![ContentBlock::ToolResult {
+                tool_use_id: id.to_string(),
+                content: content.to_string(),
+                is_error: None,
+                content_blocks: None,
+            }],
+        }
+    }
+
+    fn artifact_record(tool_call_id: &str, raw: &str) -> ArtifactRecord {
+        ArtifactRecord {
+            id: crate::artifacts::artifact_id_for_tool_call(tool_call_id),
+            kind: ArtifactKind::ToolOutput,
+            session_id: "session-123".to_string(),
+            tool_call_id: tool_call_id.to_string(),
+            tool_name: "exec_shell".to_string(),
+            created_at: Utc::now(),
+            byte_size: raw.len() as u64,
+            preview: "checking crate ... error[E0425]".to_string(),
+            storage_path: PathBuf::from("artifacts").join("art_call-big.txt"),
+        }
+    }
+
+    #[test]
+    fn compacts_large_tool_result_to_artifact_receipt() {
+        let raw = "RAW_SENTINEL\n".repeat(2_000);
+        let messages = vec![
+            tool_use_message(
+                "call-big",
+                "exec_shell",
+                json!({"command": "cargo test -p codewhale-tui"}),
+            ),
+            tool_result_message("call-big", &raw),
+        ];
+        let artifacts = vec![artifact_record("call-big", &raw)];
+
+        let (compacted, stats) = compact_messages_for_persistence(&messages, &artifacts);
+        let ContentBlock::ToolResult { content, .. } = &compacted[1].content[0] else {
+            panic!("expected tool result");
+        };
+
+        assert_eq!(stats.compacted_count, 1);
+        assert_eq!(stats.artifact_receipts, 1);
+        assert!(!content.contains("RAW_SENTINEL"));
+        assert!(content.contains("[TOOL_OUTPUT_RECEIPT]"));
+        assert!(content.contains("tool: exec_shell"));
+        assert!(content.contains("detail_handle: art_call-big"));
+        assert!(content.contains("retrieve: retrieve_tool_result ref=art_call-big"));
+        assert!(
+            content.contains("command_or_query: {\"command\":\"cargo test -p codewhale-tui\"}")
+        );
+    }
+
+    #[test]
+    fn compacts_large_tool_result_to_sha_receipt_when_no_artifact_exists() {
+        let _guard = crate::tools::truncate::TEST_SPILLOVER_GUARD
+            .lock()
+            .unwrap_or_else(|err| err.into_inner());
+        let tmp = tempdir().expect("tempdir");
+        let prior = crate::tools::truncate::set_test_spillover_root(Some(
+            tmp.path().join(".deepseek").join("tool_outputs"),
+        ));
+        struct Restore(Option<PathBuf>);
+        impl Drop for Restore {
+            fn drop(&mut self) {
+                crate::tools::truncate::set_test_spillover_root(self.0.take());
+            }
+        }
+        let _restore = Restore(prior);
+
+        let raw = format!("{}\n{}", "H".repeat(320), "NO_ARTIFACT_RAW\n".repeat(2_000));
+        let sha = sha256_hex(raw.as_bytes());
+        let messages = vec![
+            tool_use_message("call-big", "grep_files", json!({"pattern": "TODO"})),
+            tool_result_message("call-big", &raw),
+        ];
+
+        let (compacted, stats) = compact_messages_for_persistence(&messages, &[]);
+        let ContentBlock::ToolResult { content, .. } = &compacted[1].content[0] else {
+            panic!("expected tool result");
+        };
+
+        assert_eq!(stats.compacted_count, 1);
+        assert_eq!(stats.sha_receipts, 1);
+        assert!(!content.contains("NO_ARTIFACT_RAW"));
+        assert!(content.contains(&format!("detail_handle: sha:{sha}")));
+        assert!(content.contains(&format!("retrieve: retrieve_tool_result ref=sha:{sha}")));
+        let path = crate::tools::truncate::sha_spillover_path(&sha).expect("sha path");
+        assert_eq!(std::fs::read_to_string(path).expect("read sha"), raw);
+    }
+
+    #[test]
+    fn small_tool_results_remain_inline() {
+        let messages = vec![
+            tool_use_message("call-small", "exec_shell", json!({"command": "pwd"})),
+            tool_result_message("call-small", "ok"),
+        ];
+
+        let (compacted, stats) = compact_messages_for_persistence(&messages, &[]);
+        let ContentBlock::ToolResult { content, .. } = &compacted[1].content[0] else {
+            panic!("expected tool result");
+        };
+
+        assert_eq!(content, "ok");
+        assert_eq!(stats.compacted_count, 0);
+    }
+
+    #[test]
+    fn status_reports_raw_large_receipts_and_artifacts() {
+        let raw = "RAW_STATUS\n".repeat(2_000);
+        let receipt = "[TOOL_OUTPUT_RECEIPT]\ndetail_handle: art_call-big";
+        let messages = vec![
+            tool_result_message("call-raw", &raw),
+            tool_result_message("call-receipt", receipt),
+        ];
+        let artifacts = vec![ArtifactRecord {
+            storage_path: Path::new("artifacts/art_call-big.txt").to_path_buf(),
+            ..artifact_record("call-big", &raw)
+        }];
+
+        let status = tool_output_status(&messages, &artifacts);
+        assert_eq!(status.raw_large_count, 1);
+        assert_eq!(status.receipt_count, 1);
+        assert_eq!(status.artifact_count, 1);
+
+        let rendered = format_tool_output_status(&status);
+        assert!(rendered.contains("raw over cap"));
+        assert!(rendered.contains("compact receipt"));
+        assert!(rendered.contains("artifact"));
+    }
+}
diff --git a/crates/tui/src/tools/apply_patch.rs b/crates/tui/src/tools/apply_patch.rs
index f956a802..71978017 100644
--- a/crates/tui/src/tools/apply_patch.rs
+++ b/crates/tui/src/tools/apply_patch.rs
@@ -56,6 +56,22 @@ pub struct FileSummary {
     pub deleted: bool,
 }
 
+/// No-mutation summary of what an `apply_patch` input intends to touch.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ApplyPatchPreflight {
+    pub touched_files: Vec<String>,
+    pub files_total: usize,
+    pub hunks_total: usize,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub creates: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub deletes: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub path_override: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub header_path_mismatch: Option<String>,
+}
+
 /// A single hunk in a unified diff
 #[derive(Debug, Clone)]
 pub struct Hunk {
@@ -132,6 +148,19 @@ struct HunkApplyStats {
     hunks_with_fuzz: usize,
 }
 
+#[derive(Debug, Clone)]
+enum ApplyPatchPreflightKind {
+    Changes,
+    PathOverride { path: String, hunks: Vec<Hunk> },
+    FilePatches(Vec<FilePatch>),
+}
+
+#[derive(Debug, Clone)]
+struct ApplyPatchPreflightPlan {
+    summary: ApplyPatchPreflight,
+    kind: ApplyPatchPreflightKind,
+}
+
 // === Errors ===
 
 #[derive(Debug, Error)]
@@ -212,6 +241,7 @@ impl ToolSpec for ApplyPatchTool {
         let fuzz = optional_u64(&input, "fuzz", MAX_FUZZ as u64).min(MAX_FUZZ as u64);
         let fuzz = usize::try_from(fuzz).unwrap_or(MAX_FUZZ);
         let create_if_missing = optional_bool(&input, "create_if_missing", false);
+        let preflight = preflight_apply_patch_plan(&input)?;
 
         if let Some(changes_value) = input.get("changes") {
             let (pending, stats) = build_pending_writes_from_changes(changes_value, context)?;
@@ -233,6 +263,8 @@ impl ToolSpec for ApplyPatchTool {
             };
             let mut tool_result = ToolResult::json(&result)
                 .map_err(|e| ToolError::execution_failed(e.to_string()))?;
+            tool_result =
+                tool_result.with_metadata(apply_patch_preflight_metadata(&preflight.summary));
             if !diag_block.is_empty() {
                 tool_result.content.push('\n');
                 tool_result.content.push_str(&diag_block);
@@ -240,38 +272,21 @@ impl ToolSpec for ApplyPatchTool {
             return Ok(tool_result);
         }
 
-        let patch_text = required_str(&input, "patch")?;
-        let path_override = optional_str(&input, "path");
-        let patch_shape = inspect_patch_shape(patch_text);
-        validate_patch_shape(&patch_shape, path_override)?;
-        let mismatch_note = path_override.and_then(|path| diff_header_mismatch(path, &patch_shape));
-        let file_patches = if let Some(path) = path_override {
-            let hunks = parse_unified_diff(patch_text)?;
-            if hunks.is_empty() {
-                return Err(ToolError::invalid_input(
-                    "Patch did not contain any hunks (`@@ ... @@`). Provide a unified diff hunk.",
-                ));
+        let file_patches = match preflight.kind {
+            ApplyPatchPreflightKind::Changes => {
+                unreachable!("changes input returned before patch execution")
             }
-            vec![FilePatch {
-                path: path.to_string(),
+            ApplyPatchPreflightKind::PathOverride { path, hunks } => vec![FilePatch {
+                path,
                 hunks,
                 delete_after: false,
                 create_if_missing,
-            }]
-        } else {
-            let file_patches = parse_unified_diff_files(patch_text, create_if_missing)?;
-            if file_patches.is_empty() {
-                return Err(ToolError::invalid_input(
-                    "No valid file patches found. Ensure the patch includes `---`/`+++` headers or provide `path`.",
-                ));
-            }
-            file_patches
+            }],
+            ApplyPatchPreflightKind::FilePatches(file_patches) => file_patches,
         };
 
         let (pending, mut stats) = build_pending_writes_from_patches(file_patches, context, fuzz)?;
-        if stats.header_path_mismatch.is_none() {
-            stats.header_path_mismatch = mismatch_note;
-        }
+        stats.header_path_mismatch = preflight.summary.header_path_mismatch.clone();
         apply_pending_writes(&pending)?;
         // Resolve absolute paths for LSP diagnostics query.
         let abs_paths: Vec<PathBuf> = pending
@@ -294,6 +309,7 @@ impl ToolSpec for ApplyPatchTool {
         };
         let mut tool_result =
             ToolResult::json(&result).map_err(|e| ToolError::execution_failed(e.to_string()))?;
+        tool_result = tool_result.with_metadata(apply_patch_preflight_metadata(&preflight.summary));
         if !diag_block.is_empty() {
             tool_result.content.push('\n');
             tool_result.content.push_str(&diag_block);
@@ -302,6 +318,143 @@ impl ToolSpec for ApplyPatchTool {
     }
 }
 
+/// Parse `apply_patch` input into a reusable, no-mutation preflight summary.
+///
+/// This deliberately stops before workspace resolution or file reads. It is
+/// suitable for policy checks, audit logs, diagnostics hooks, and future undo
+/// planning that must know the target files before mutation.
+pub fn preflight_apply_patch(input: &Value) -> Result<ApplyPatchPreflight, ToolError> {
+    Ok(preflight_apply_patch_plan(input)?.summary)
+}
+
+fn preflight_apply_patch_plan(input: &Value) -> Result<ApplyPatchPreflightPlan, ToolError> {
+    let create_if_missing = optional_bool(input, "create_if_missing", false);
+
+    if let Some(changes_value) = input.get("changes") {
+        return Ok(ApplyPatchPreflightPlan {
+            summary: preflight_changes(changes_value)?,
+            kind: ApplyPatchPreflightKind::Changes,
+        });
+    }
+
+    let patch_text = required_str(input, "patch")?;
+    let path_override = optional_str(input, "path");
+    let patch_shape = inspect_patch_shape(patch_text);
+    validate_patch_shape(&patch_shape, path_override)?;
+    let header_path_mismatch =
+        path_override.and_then(|path| diff_header_mismatch(path, &patch_shape));
+
+    if let Some(path) = path_override {
+        let hunks = parse_unified_diff(patch_text)?;
+        if hunks.is_empty() {
+            return Err(ToolError::invalid_input(
+                "Patch did not contain any hunks (`@@ ... @@`). Provide a unified diff hunk.",
+            ));
+        }
+        return Ok(ApplyPatchPreflightPlan {
+            summary: ApplyPatchPreflight {
+                touched_files: vec![path.to_string()],
+                files_total: 1,
+                hunks_total: hunks.len(),
+                creates: if create_if_missing {
+                    vec![path.to_string()]
+                } else {
+                    Vec::new()
+                },
+                deletes: Vec::new(),
+                path_override: Some(path.to_string()),
+                header_path_mismatch,
+            },
+            kind: ApplyPatchPreflightKind::PathOverride {
+                path: path.to_string(),
+                hunks,
+            },
+        });
+    }
+
+    let file_patches = parse_unified_diff_files(patch_text, create_if_missing)?;
+    if file_patches.is_empty() {
+        return Err(ToolError::invalid_input(
+            "No valid file patches found. Ensure the patch includes `---`/`+++` headers or provide `path`.",
+        ));
+    }
+
+    let mut touched_files = Vec::new();
+    let mut creates = Vec::new();
+    let mut deletes = Vec::new();
+    let mut hunks_total = 0;
+    for file_patch in &file_patches {
+        if file_patch.hunks.is_empty() {
+            return Err(ToolError::invalid_input(format!(
+                "Patch section for `{}` has no hunks (`@@ ... @@`).",
+                file_patch.path
+            )));
+        }
+        push_unique(&mut touched_files, file_patch.path.clone());
+        hunks_total += file_patch.hunks.len();
+        if file_patch.create_if_missing && !file_patch.delete_after {
+            push_unique(&mut creates, file_patch.path.clone());
+        }
+        if file_patch.delete_after {
+            push_unique(&mut deletes, file_patch.path.clone());
+        }
+    }
+
+    Ok(ApplyPatchPreflightPlan {
+        summary: ApplyPatchPreflight {
+            files_total: file_patches.len(),
+            touched_files,
+            hunks_total,
+            creates,
+            deletes,
+            path_override: None,
+            header_path_mismatch,
+        },
+        kind: ApplyPatchPreflightKind::FilePatches(file_patches),
+    })
+}
+
+fn preflight_changes(changes_value: &Value) -> Result<ApplyPatchPreflight, ToolError> {
+    let changes = changes_value.as_array().ok_or_else(|| {
+        ToolError::invalid_input("`changes` must be an array of objects like {path, content}")
+    })?;
+    if changes.is_empty() {
+        return Err(ToolError::invalid_input("`changes` cannot be empty"));
+    }
+
+    let mut touched_files = Vec::new();
+    for change in changes {
+        let path = change
+            .get("path")
+            .and_then(Value::as_str)
+            .ok_or_else(|| ToolError::missing_field("changes[].path"))?;
+        let _content = change
+            .get("content")
+            .and_then(Value::as_str)
+            .ok_or_else(|| ToolError::missing_field("changes[].content"))?;
+        push_unique(&mut touched_files, path.to_string());
+    }
+
+    Ok(ApplyPatchPreflight {
+        files_total: changes.len(),
+        touched_files,
+        hunks_total: 0,
+        creates: Vec::new(),
+        deletes: Vec::new(),
+        path_override: None,
+        header_path_mismatch: None,
+    })
+}
+
+fn apply_patch_preflight_metadata(preflight: &ApplyPatchPreflight) -> Value {
+    let mut metadata =
+        serde_json::to_value(preflight).expect("ApplyPatchPreflight should serialize");
+    if let Some(object) = metadata.as_object_mut() {
+        object.insert("event".to_string(), json!("apply_patch.preflight"));
+    }
+    metadata
+}
+
 /// Parse a unified diff into hunks
 fn parse_unified_diff(patch: &str) -> Result<Vec<Hunk>, ToolError> {
     let mut hunks = Vec::new();
@@ -1056,6 +1209,101 @@ mod tests {
         assert_eq!(hunks[0].new_count, 3);
     }
 
+    #[test]
+    fn test_preflight_apply_patch_with_path_override() {
+        let patch = r"@@ -1,2 +1,2 @@
+ old
+-value
++new-value
+";
+
+        let preflight = preflight_apply_patch(&json!({
+            "path": "src/lib.rs",
+            "patch": patch
+        }))
+        .expect("preflight");
+
+        assert_eq!(preflight.touched_files, vec!["src/lib.rs"]);
+        assert_eq!(preflight.files_total, 1);
+        assert_eq!(preflight.hunks_total, 1);
+        assert_eq!(preflight.path_override.as_deref(), Some("src/lib.rs"));
+    }
+
+    #[test]
+    fn test_preflight_apply_patch_multi_file_create_and_delete() {
+        let patch = r"diff --git a/new.rs b/new.rs
+--- /dev/null
++++ b/new.rs
+@@ -0,0 +1 @@
++fn added() {}
+diff --git a/old.rs b/old.rs
+--- a/old.rs
++++ /dev/null
+@@ -1 +0,0 @@
+-fn old() {}
+";
+
+        let preflight = preflight_apply_patch(&json!({ "patch": patch })).expect("preflight");
+
+        assert_eq!(preflight.touched_files, vec!["new.rs", "old.rs"]);
+        assert_eq!(preflight.files_total, 2);
+        assert_eq!(preflight.hunks_total, 2);
+        assert_eq!(preflight.creates, vec!["new.rs"]);
+        assert_eq!(preflight.deletes, vec!["old.rs"]);
+    }
+
+    #[test]
+    fn test_preflight_apply_patch_changes_list() {
+        let preflight = preflight_apply_patch(&json!({
+            "changes": [
+                { "path": "one.txt", "content": "one" },
+                { "path": "two.txt", "content": "two" }
+            ]
+        }))
+        .expect("preflight");
+
+        assert_eq!(preflight.touched_files, vec!["one.txt", "two.txt"]);
+        assert_eq!(preflight.files_total, 2);
+        assert_eq!(preflight.hunks_total, 0);
+    }
+
+    #[test]
+    fn test_preflight_changes_files_total_counts_entries() {
+        let preflight = preflight_apply_patch(&json!({
+            "changes": [
+                { "path": "same.txt", "content": "one" },
+                { "path": "same.txt", "content": "two" }
+            ]
+        }))
+        .expect("preflight");
+
+        assert_eq!(preflight.touched_files, vec!["same.txt"]);
+        assert_eq!(preflight.files_total, 2);
+    }
+
+    #[test]
+    fn test_preflight_patch_files_total_counts_sections() {
+        let patch = r"diff --git a/same.txt b/same.txt
+--- a/same.txt
++++ b/same.txt
+@@ -1,1 +1,1 @@
+-one
++two
+diff --git a/same.txt b/same.txt
+--- a/same.txt
++++ b/same.txt
+@@ -2,1 +2,1 @@
+-three
++four
+";
+
+        let preflight = preflight_apply_patch(&json!({ "patch": patch })).expect("preflight");
+
+        assert_eq!(preflight.touched_files, vec!["same.txt"]);
+        assert_eq!(preflight.files_total, 2);
+        assert_eq!(preflight.hunks_total, 2);
+    }
+
     #[test]
     fn test_apply_hunk_simple() {
         let mut lines = vec![
@@ -1160,6 +1408,30 @@ mod tests {
             .expect("execute");
 
         assert!(result.success);
+        assert_eq!(
+            result.metadata.as_ref().unwrap()["event"],
+            "apply_patch.preflight"
+        );
+        assert_eq!(
+            result.metadata.as_ref().unwrap()["touched_files"],
+            json!(["test.txt"])
+        );
+        assert!(
+            result
+                .metadata
+                .as_ref()
+                .unwrap()
+                .get("header_path_mismatch")
+                .is_none()
+        );
+        assert!(
+            result
+                .metadata
+                .as_ref()
+                .unwrap()
+                .get("path_override")
+                .is_some()
+        );
         let patch_result = parse_patch_result(result);
         assert_eq!(patch_result.touched_files, vec!["test.txt"]);
         assert_eq!(patch_result.hunks_applied, 1);
@@ -1246,6 +1518,12 @@ mod tests {
             .expect("execute");
 
         assert!(result.success);
+        let metadata = result.metadata.as_ref().expect("metadata");
+        assert_eq!(metadata["event"], "apply_patch.preflight");
+        assert_eq!(metadata["touched_files"], json!(["one.txt", "two.txt"]));
+        assert_eq!(metadata["files_total"], 2);
+        assert_eq!(metadata["hunks_total"], 0);
+        assert!(metadata.get("path_override").is_none());
         let patch_result = parse_patch_result(result);
         let mut touched = patch_result.touched_files.clone();
         touched.sort();
@@ -1292,6 +1570,12 @@ diff --git a/b.txt b/b.txt
             .expect("execute");
 
         assert!(result.success);
+        let metadata = result.metadata.as_ref().expect("metadata");
+        assert_eq!(metadata["event"], "apply_patch.preflight");
+        assert_eq!(metadata["touched_files"], json!(["a.txt", "b.txt"]));
+        assert_eq!(metadata["files_total"], 2);
+        assert_eq!(metadata["hunks_total"], 2);
+        assert!(metadata.get("path_override").is_none());
         let patch_result = parse_patch_result(result);
         let mut touched = patch_result.touched_files.clone();
         touched.sort();
@@ -1407,6 +1691,13 @@ diff --git a/b.txt b/b.txt
             .execute(json!({"path": "override.txt", "patch": patch}), &ctx)
             .await
             .expect("execute");
+        let metadata = result.metadata.as_ref().expect("metadata");
+        assert!(
+            metadata["header_path_mismatch"]
+                .as_str()
+                .unwrap()
+                .contains("headers reference `other.txt`")
+        );
         let patch_result = parse_patch_result(result);
         assert!(
             patch_result
diff --git a/crates/tui/src/tools/cargo_failure_summary.rs b/crates/tui/src/tools/cargo_failure_summary.rs
new file mode 100644
index 00000000..00033f6d
--- /dev/null
+++ b/crates/tui/src/tools/cargo_failure_summary.rs
@@ -0,0 +1,469 @@
+//! Compact summaries for Cargo failures.
+//!
+//! Cargo output can be large and noisy. This module extracts stable failure
+//! signals for tool metadata so context compaction can preserve the actionable
+//! lines without re-running `cargo test | tail`.
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+
+const MAX_ITEMS: usize = 8;
+const MAX_SUMMARY_CHARS: usize = 1_200;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum CargoFailureKind {
+    TestFailure,
+    CompileError,
+    CargoFailure,
+}
+
+impl CargoFailureKind {
+    fn label(&self) -> &'static str {
+        match self {
+            Self::TestFailure => "test_failure",
+            Self::CompileError => "compile_error",
+            Self::CargoFailure => "cargo_failure",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub(crate) struct CargoFailureSummary {
+    pub(crate) kind: CargoFailureKind,
+    pub(crate) summary: String,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) failing_tests: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) error_codes: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) primary_errors: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub(crate) panic_locations: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) test_result: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) final_error: Option<String>,
+}
+
+impl CargoFailureSummary {
+    pub(crate) fn to_metadata_value(&self) -> Value {
+        json!(self)
+    }
+}
+
+pub(crate) fn summarize_cargo_failure(
+    command: &str,
+    stdout: &str,
+    stderr: &str,
+    exit_code: Option<i32>,
+) -> Option<CargoFailureSummary> {
+    if exit_code == Some(0) || !looks_like_cargo_command(command) {
+        return None;
+    }
+
+    let mut failing_tests = Vec::new();
+    let mut error_codes = Vec::new();
+    let mut primary_errors = Vec::new();
+    let mut panic_locations = Vec::new();
+    let mut test_result = None;
+    let mut final_error = None;
+
+    for line in stderr.lines().chain(stdout.lines()) {
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+
+        if let Some(test) = parse_failed_test_line(trimmed) {
+            push_unique_limited(&mut failing_tests, test);
+        }
+        if let Some(test) = parse_failure_header(trimmed) {
+            push_unique_limited(&mut failing_tests, test);
+        }
+        if let Some(code) = parse_error_code(trimmed) {
+            push_unique_limited(&mut error_codes, code);
+        }
+        if is_primary_error_line(trimmed) {
+            push_unique_limited(&mut primary_errors, trimmed.to_string());
+        }
+        if trimmed.contains("panicked at ") {
+            push_unique_limited(&mut panic_locations, trimmed.to_string());
+        }
+        if trimmed.starts_with("test result:") {
+            test_result = Some(trimmed.to_string());
+        }
+        if trimmed.starts_with("error: could not compile")
+            || trimmed.starts_with("error: aborting due to")
+            || trimmed.starts_with("error: test failed")
+        {
+            final_error = Some(trimmed.to_string());
+        }
+    }
+
+    let kind = classify_failure(&failing_tests, &primary_errors, test_result.as_deref());
+    if !has_actionable_signal(
+        &failing_tests,
+        &error_codes,
+        &primary_errors,
+        &panic_locations,
+        test_result.as_deref(),
+        final_error.as_deref(),
+    ) {
+        return None;
+    }
+    let summary = build_summary(
+        &kind,
+        &failing_tests,
+        &error_codes,
+        &primary_errors,
+        &panic_locations,
+        test_result.as_deref(),
+        final_error.as_deref(),
+    );
+
+    Some(CargoFailureSummary {
+        kind,
+        summary,
+        failing_tests,
+        error_codes,
+        primary_errors,
+        panic_locations,
+        test_result,
+        final_error,
+    })
+}
+
+fn looks_like_cargo_command(command: &str) -> bool {
+    let Some(tokens) = shlex::split(command) else {
+        return false;
+    };
+
+    let mut expect_command = true;
+    for (idx, raw_token) in tokens.iter().enumerate() {
+        let token = normalize_shell_token(raw_token);
+        if token.is_empty() {
+            continue;
+        }
+        if is_shell_separator(token) {
+            expect_command = true;
+            continue;
+        }
+        if !expect_command {
+            continue;
+        }
+        if looks_like_env_assignment(token) {
+            continue;
+        }
+        if is_cargo_binary(token) {
+            return cargo_subcommand(&tokens[idx + 1..]).is_some();
+        }
+        expect_command = false;
+    }
+
+    false
+}
+
+fn parse_failed_test_line(line: &str) -> Option<String> {
+    let rest = line.strip_prefix("test ")?;
+    let (name, status) = rest.rsplit_once(" ... ")?;
+    (status == "FAILED").then(|| name.trim().to_string())
+}
+
+fn parse_failure_header(line: &str) -> Option<String> {
+    let rest = line.strip_prefix("---- ")?;
+    let name = rest.strip_suffix(" stdout ----")?;
+    Some(name.trim().to_string())
+}
+
+fn parse_error_code(line: &str) -> Option<String> {
+    let rest = line.strip_prefix("error[")?;
+    let (code, _) = rest.split_once("]")?;
+    Some(code.to_string())
+}
+
+fn is_primary_error_line(line: &str) -> bool {
+    line.starts_with("error[")
+        || (line.starts_with("error:") && !line.starts_with("error: test failed"))
+}
+
+fn classify_failure(
+    failing_tests: &[String],
+    primary_errors: &[String],
+    test_result: Option<&str>,
+) -> CargoFailureKind {
+    if !failing_tests.is_empty()
+        || test_result.is_some_and(|line| line.to_ascii_lowercase().contains("failed"))
+    {
+        CargoFailureKind::TestFailure
+    } else if !primary_errors.is_empty() {
+        CargoFailureKind::CompileError
+    } else {
+        CargoFailureKind::CargoFailure
+    }
+}
+
+fn has_actionable_signal(
+    failing_tests: &[String],
+    error_codes: &[String],
+    primary_errors: &[String],
+    panic_locations: &[String],
+    test_result: Option<&str>,
+    final_error: Option<&str>,
+) -> bool {
+    !failing_tests.is_empty()
+        || !error_codes.is_empty()
+        || !primary_errors.is_empty()
+        || !panic_locations.is_empty()
+        || test_result.is_some()
+        || final_error.is_some()
+}
+
+fn build_summary(
+    kind: &CargoFailureKind,
+    failing_tests: &[String],
+    error_codes: &[String],
+    primary_errors: &[String],
+    panic_locations: &[String],
+    test_result: Option<&str>,
+    final_error: Option<&str>,
+) -> String {
+    let mut lines = Vec::new();
+    lines.push(format!("Cargo failure kind: {}.", kind.label()));
+    if !failing_tests.is_empty() {
+        lines.push(format!("Failing tests: {}.", failing_tests.join(", ")));
+    }
+    if !error_codes.is_empty() {
+        lines.push(format!("Rust error codes: {}.", error_codes.join(", ")));
+    }
+    if let Some(line) = primary_errors.first() {
+        lines.push(format!("Primary error: {line}"));
+    }
+    if let Some(line) = panic_locations.first() {
+        lines.push(format!("Panic: {line}"));
+    }
+    if let Some(line) = test_result {
+        lines.push(line.to_string());
+    }
+    if let Some(line) = final_error {
+        lines.push(line.to_string());
+    }
+    truncate_chars(&lines.join("\n"), MAX_SUMMARY_CHARS)
+}
+
+fn normalize_shell_token(token: &str) -> &str {
+    token.trim_matches(|ch| matches!(ch, '(' | ')' | '{' | '}'))
+}
+
+fn is_shell_separator(token: &str) -> bool {
+    matches!(token, "&&" | "||" | ";" | "|")
+}
+
+fn looks_like_env_assignment(token: &str) -> bool {
+    let Some((name, _)) = token.split_once('=') else {
+        return false;
+    };
+    !name.is_empty()
+        && name
+            .bytes()
+            .all(|byte| byte == b'_' || byte.is_ascii_alphanumeric())
+        && !name.as_bytes()[0].is_ascii_digit()
+}
+
+fn is_cargo_binary(token: &str) -> bool {
+    let name = token.rsplit(['/', '\\']).next().unwrap_or(token);
+    name.eq_ignore_ascii_case("cargo") || name.eq_ignore_ascii_case("cargo.exe")
+}
+
+fn cargo_subcommand(tokens: &[String]) -> Option<&str> {
+    let mut idx = 0;
+    while let Some(raw_token) = tokens.get(idx) {
+        let token = normalize_shell_token(raw_token);
+        if token.is_empty() {
+            idx += 1;
+            continue;
+        }
+        if is_shell_separator(token) {
+            return None;
+        }
+        if token.starts_with('+') {
+            idx += 1;
+            continue;
+        }
+        if token.starts_with('-') {
+            if cargo_global_flag_takes_value(token) {
+                idx += 2;
+            } else {
+                idx += 1;
+            }
+            continue;
+        }
+        return is_supported_cargo_subcommand(token).then_some(token);
+    }
+    None
+}
+
+fn cargo_global_flag_takes_value(token: &str) -> bool {
+    if token.contains('=') {
+        return false;
+    }
+    matches!(
+        token,
+        "--color"
+            | "--config"
+            | "-C"
+            | "--jobs"
+            | "-j"
+            | "--lockfile-path"
+            | "--manifest-path"
+            | "--message-format"
+            | "--package"
+            | "-p"
+            | "--target"
+            | "--target-dir"
+            | "-Z"
+    )
+}
+
+fn is_supported_cargo_subcommand(token: &str) -> bool {
+    matches!(
+        token,
+        "test" | "check" | "build" | "clippy" | "run" | "t" | "c" | "b" | "r"
+    )
+}
+
+fn push_unique_limited(target: &mut Vec<String>, value: String) {
+    if target.len() >= MAX_ITEMS || target.iter().any(|existing| existing == &value) {
+        return;
+    }
+    target.push(value);
+}
+
+fn truncate_chars(text: &str, max_chars: usize) -> String {
+    if let Some((idx, _)) = text.char_indices().nth(max_chars) {
+        if max_chars < 3 {
+            return text[..idx].to_string();
+        }
+        let truncate_at = text
+            .char_indices()
+            .nth(max_chars - 3)
+            .map(|(idx, _)| idx)
+            .unwrap_or(0);
+        format!("{}...", &text[..truncate_at])
+    } else {
+        text.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn summarizes_failed_libtest_output() {
+        let stdout = r"
+running 1 test
+test tests::fails ... FAILED
+
+failures:
+
+---- tests::fails stdout ----
+thread 'tests::fails' panicked at src/lib.rs:7:9:
+assertion `left == right` failed
+
+test result: FAILED. 0 passed; 1 failed; 0 ignored; finished in 0.00s
+";
+        let summary =
+            summarize_cargo_failure("cargo test", stdout, "", Some(101)).expect("summary");
+
+        assert_eq!(summary.kind, CargoFailureKind::TestFailure);
+        assert_eq!(summary.failing_tests, vec!["tests::fails"]);
+        assert!(summary.summary.contains("Failing tests: tests::fails"));
+        assert!(summary.test_result.unwrap().contains("1 failed"));
+    }
+
+    #[test]
+    fn summarizes_rustc_compile_error() {
+        let stderr = r#"
+error[E0308]: mismatched types
+  --> src/lib.rs:2:5
+   |
+2  |     "" 
+   |     ^^ expected `i32`, found `&str`
+error: could not compile `demo` (lib) due to 1 previous error
+"#;
+        let summary =
+            summarize_cargo_failure("cargo check", "", stderr, Some(101)).expect("summary");
+
+        assert_eq!(summary.kind, CargoFailureKind::CompileError);
+        assert_eq!(summary.error_codes, vec!["E0308"]);
+        assert!(summary.primary_errors[0].contains("mismatched types"));
+        assert!(summary.final_error.unwrap().contains("could not compile"));
+    }
+
+    #[test]
+    fn recognizes_cargo_aliases_and_uncoded_errors() {
+        let stderr = "error: cannot find value `missing` in this scope\n";
+        let summary = summarize_cargo_failure("cargo c", "", stderr, Some(101)).expect("summary");
+
+        assert_eq!(summary.kind, CargoFailureKind::CompileError);
+        assert_eq!(
+            summary.primary_errors,
+            vec!["error: cannot find value `missing` in this scope"]
+        );
+    }
+
+    #[test]
+    fn recognizes_tokenized_cargo_invocations() {
+        assert!(
+            summarize_cargo_failure(
+                "cargo +nightly --manifest-path demo/Cargo.toml test",
+                "test tests::fails ... FAILED\n",
+                "",
+                Some(101),
+            )
+            .is_some()
+        );
+        assert!(
+            summarize_cargo_failure(
+                "DEMO=1 cargo --locked run",
+                "",
+                "error: process didn't exit successfully\n",
+                Some(101),
+            )
+            .is_some()
+        );
+        assert!(
+            summarize_cargo_failure(
+                "echo cargo test && false",
+                "test tests::fails ... FAILED\n",
+                "",
+                Some(1),
+            )
+            .is_none()
+        );
+    }
+
+    #[test]
+    fn skips_generic_cargo_failure_without_actionable_signal() {
+        assert!(
+            summarize_cargo_failure("cargo test", "build failed", "command failed", Some(1))
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn truncate_chars_respects_tiny_limits() {
+        assert_eq!(truncate_chars("abcdef", 0), "");
+        assert_eq!(truncate_chars("abcdef", 1), "a");
+        assert_eq!(truncate_chars("abcdef", 2), "ab");
+        assert_eq!(truncate_chars("abcdef", 3), "...");
+        assert_eq!(truncate_chars("abcdef", 4), "a...");
+    }
+
+    #[test]
+    fn ignores_successful_or_non_cargo_commands() {
+        assert!(summarize_cargo_failure("cargo test", "", "", Some(0)).is_none());
+        assert!(summarize_cargo_failure("npm test", "failed", "", Some(1)).is_none());
+    }
+}
diff --git a/crates/tui/src/tools/diagnostics.rs b/crates/tui/src/tools/diagnostics.rs
index 2472a523..b03011da 100644
--- a/crates/tui/src/tools/diagnostics.rs
+++ b/crates/tui/src/tools/diagnostics.rs
@@ -28,6 +28,8 @@ struct DiagnosticsOutput {
     git_error: Option<String>,
     sandbox_available: bool,
     sandbox_type: Option<String>,
+    bwrap_available: bool,
+    cgroup_version: Option<u8>,
     rustc_version: Option<String>,
     cargo_version: Option<String>,
     /// User-trusted external paths the agent may access from this workspace
@@ -87,6 +89,12 @@ impl ToolSpec for DiagnosticsTool {
         let sandbox_type = crate::sandbox::get_platform_sandbox().map(|s| s.to_string());
         let sandbox_available = sandbox_type.is_some();
 
+        // Bubblewrap availability (#2184).
+        let bwrap_available = probe_bwrap_available();
+
+        // Cgroup version (Linux only).
+        let cgroup_version = probe_cgroup_version();
+
         let trusted_external_paths = context
             .trusted_external_paths
             .iter()
@@ -101,6 +109,8 @@ impl ToolSpec for DiagnosticsTool {
             git_error: git.error,
             sandbox_available,
             sandbox_type,
+            bwrap_available,
+            cgroup_version,
             rustc_version: probe_version("rustc", &["--version"], &context.workspace),
             cargo_version: probe_version("cargo", &["--version"], &context.workspace),
             trusted_external_paths,
@@ -144,6 +154,36 @@ fn probe_git(workspace: &Path) -> GitProbe {
     }
 }
 
+fn probe_bwrap_available() -> bool {
+    #[cfg(target_os = "linux")]
+    {
+        crate::sandbox::bwrap::is_available()
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        false
+    }
+}
+
+fn probe_cgroup_version() -> Option<u8> {
+    #[cfg(target_os = "linux")]
+    {
+        let path = std::path::Path::new("/sys/fs/cgroup/cgroup.controllers");
+        if path.exists() {
+            return Some(2);
+        }
+        let path = std::path::Path::new("/sys/fs/cgroup");
+        if path.exists() {
+            return Some(1);
+        }
+        None
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        None
+    }
+}
+
 fn probe_version(program: &str, args: &[&str], cwd: &Path) -> Option<String> {
     run_command(program, args, cwd).into_success()
 }
diff --git a/crates/tui/src/tools/fetch_url.rs b/crates/tui/src/tools/fetch_url.rs
index cdf0b128..194392af 100644
--- a/crates/tui/src/tools/fetch_url.rs
+++ b/crates/tui/src/tools/fetch_url.rs
@@ -389,8 +389,14 @@ fn validate_dns_resolved_ip(
         return Ok(());
     }
 
+    // Allow the resolved IP past the restricted-IP block if either:
+    //   * it falls inside a configured fake-IP placeholder range (a TUN /
+    //     transparent-proxy setup in `fake-ip` mode resolves every host into a
+    //     reserved range such as `198.18.0.0/15`), or
+    //   * the host is on the explicitly-trusted proxy list.
+    // Real private/loopback/link-local/metadata IPs match neither and stay blocked.
     if let Some(decider) = decider
-        && decider.trusts_proxy_fakeip_host(host)
+        && (decider.is_trusted_fakeip_addr(ip) || decider.trusts_proxy_fakeip_host(host))
     {
         decider.record_trusted_proxy_fakeip_allow(host, "fetch_url");
         return Ok(());
diff --git a/crates/tui/src/tools/file.rs b/crates/tui/src/tools/file.rs
index 2ec2fe9b..671f1366 100644
--- a/crates/tui/src/tools/file.rs
+++ b/crates/tui/src/tools/file.rs
@@ -256,6 +256,49 @@ fn parse_pages_arg(spec: &str) -> Option<(u32, u32)> {
     }
 }
 
+/// Clean PDF-extracted text for TUI display: collapse consecutive blank
+/// lines (more than 1 becomes 1), replace NUL bytes with U+FFFD, replace
+/// non-breaking spaces with regular spaces, and trim trailing whitespace
+/// on each line. Produces output that won't clutter the transcript with
+/// vertical gaps or invisible control characters.
+fn clean_pdf_text(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    let mut blank_run = 0usize;
+    let mut any_content = false;
+    for line in raw.lines() {
+        let trimmed = line.trim_end();
+        if trimmed.is_empty() {
+            blank_run = blank_run.saturating_add(1);
+            if blank_run <= 1 {
+                out.push('\n');
+            }
+        } else {
+            blank_run = 0;
+            any_content = true;
+            // Push cleaned characters directly — avoids a per-line
+            // temporary String allocation.
+            for c in trimmed.chars() {
+                match c {
+                    '\0' => out.push('\u{FFFD}'),
+                    '\u{A0}' => out.push(' '),
+                    other => out.push(other),
+                }
+            }
+            out.push('\n');
+        }
+    }
+    // Trim leading blank lines only — don't use str::trim() which
+    // would also strip intentional indentation (e.g. centred titles).
+    if any_content {
+        let start = out.find(|c: char| c != '\n').unwrap_or(0);
+        // Walk back from end to find the last non-newline character.
+        let end = out.rfind(|c: char| c != '\n').map_or(out.len(), |i| i + 1);
+        out[start..end].to_string()
+    } else {
+        String::new()
+    }
+}
+
 fn read_pdf(path: &Path, pages: Option<&str>) -> Result<ToolResult, ToolError> {
     // Validate the `pages` spec once, up front, so both extractor paths
     // surface the same error shape on bad input.
@@ -325,7 +368,7 @@ fn read_pdf_via_pdf_extract(
             ))
         })?
     };
-    Ok(ToolResult::success(text))
+    Ok(ToolResult::success(clean_pdf_text(&text)))
 }
 
 fn read_pdf_via_pdftotext(
@@ -382,7 +425,7 @@ fn read_pdf_via_pdftotext(
     }
 
     let text = String::from_utf8_lossy(&output.stdout).to_string();
-    Ok(ToolResult::success(text))
+    Ok(ToolResult::success(clean_pdf_text(&text)))
 }
 
 // === WriteFileTool ===
@@ -496,7 +539,7 @@ impl ToolSpec for EditFileTool {
     }
 
     fn description(&self) -> &'static str {
-        "Replace text in a single file via exact search/replace. Use this instead of `sed -i` in `exec_shell` for one unambiguous in-place edit. `search` matches exactly by default, including whitespace and indentation; set `fuzz: true` to tolerate leading-indentation differences. Returns a compact unified diff, not the full file. For structural, multi-block, or cross-file changes, use `apply_patch` or `write_file` instead."
+        "Replace text in a single file via exact search/replace. Use this instead of `sed -i` in `exec_shell` for one unambiguous in-place edit. `search` matches exactly by default; when no exact match is found the tool retries with leading-whitespace-tolerant fuzzy matching automatically. The optional `fuzz` parameter is accepted for backward compatibility and is no longer needed. Returns a compact unified diff, not the full file. For structural, multi-block, or cross-file changes, use `apply_patch` or `write_file` instead."
     }
 
     fn input_schema(&self) -> Value {
@@ -517,7 +560,7 @@ impl ToolSpec for EditFileTool {
                 },
                 "fuzz": {
                     "type": "boolean",
-                    "description": "When true, tolerate leading whitespace differences on each searched line (default false)"
+                    "description": "Deprecated: fuzzy fallback is now automatic. Accepted for backward compatibility but ignored."
                 }
             },
             "required": ["path", "search", "replace"]
@@ -540,7 +583,7 @@ impl ToolSpec for EditFileTool {
         let path_str = required_str(&input, "path")?;
         let search = required_str(&input, "search")?;
         let replace = required_str(&input, "replace")?;
-        let fuzz = optional_bool(&input, "fuzz", false);
+        let _fuzz = optional_bool(&input, "fuzz", false);
 
         if search == replace {
             return Err(ToolError::invalid_input(
@@ -555,7 +598,7 @@ impl ToolSpec for EditFileTool {
         })?;
 
         let count = contents.matches(search).count();
-        let (updated, count, fuzz_kind) = if count == 0 && fuzz {
+        let (updated, count, fuzz_kind) = if count == 0 {
             // First fallback: tolerate indentation differences.
             let indent_matches = leading_whitespace_fuzzy_matches(&contents, search);
             match indent_matches.as_slice() {
@@ -600,11 +643,6 @@ impl ToolSpec for EditFileTool {
                     )));
                 }
             }
-        } else if count == 0 {
-            return Err(ToolError::execution_failed(format!(
-                "Search string not found in {}",
-                file_path.display()
-            )));
         } else {
             (contents.replace(search, replace), count, None)
         };
@@ -1231,6 +1269,43 @@ mod tests {
         std::path::Path::new(SAMPLE_PDF_PATH).exists()
     }
 
+    #[test]
+    fn clean_pdf_text_collapses_consecutive_blank_lines() {
+        let raw = "line1\n\n\n\n\nline2\n\n\nline3";
+        let cleaned = super::clean_pdf_text(raw);
+        assert_eq!(cleaned, "line1\n\nline2\n\nline3");
+    }
+
+    #[test]
+    fn clean_pdf_text_replaces_nul_bytes_with_replacement_char() {
+        let raw = "hello\0world";
+        let cleaned = super::clean_pdf_text(raw);
+        assert!(!cleaned.contains('\0'));
+        assert!(cleaned.contains('\u{FFFD}'));
+    }
+
+    #[test]
+    fn clean_pdf_text_replaces_non_breaking_spaces() {
+        let raw = "hello\u{A0}world";
+        let cleaned = super::clean_pdf_text(raw);
+        assert!(!cleaned.contains('\u{A0}'));
+        assert_eq!(cleaned, "hello world");
+    }
+
+    #[test]
+    fn clean_pdf_text_trims_trailing_whitespace() {
+        let raw = "hello   ";
+        let cleaned = super::clean_pdf_text(raw);
+        assert_eq!(cleaned, "hello");
+    }
+
+    #[test]
+    fn clean_pdf_text_preserves_leading_indentation() {
+        let raw = "   indented line\nregular line";
+        let cleaned = super::clean_pdf_text(raw);
+        assert_eq!(cleaned, "   indented line\nregular line");
+    }
+
     #[test]
     fn read_pdf_via_pdf_extract_finds_known_title() {
         // Skip when the fixture isn't checked out (sparse clones, shallow
@@ -1480,6 +1555,41 @@ mod tests {
         assert_eq!(edited, "hi world hi");
     }
 
+    #[tokio::test]
+    async fn test_edit_file_accepts_omitted_and_explicit_fuzz() {
+        let tmp = tempdir().expect("tempdir");
+        let ctx = ToolContext::new(tmp.path().to_path_buf());
+        let tool = EditFileTool;
+
+        for (file_name, fuzz) in [
+            ("fuzz_omitted.txt", None),
+            ("fuzz_false.txt", Some(false)),
+            ("fuzz_true.txt", Some(true)),
+        ] {
+            let test_file = tmp.path().join(file_name);
+            fs::write(&test_file, "hello world").expect("write");
+
+            let mut input = serde_json::Map::from_iter([
+                ("path".to_string(), json!(file_name)),
+                ("search".to_string(), json!("hello")),
+                ("replace".to_string(), json!("hi")),
+            ]);
+            if let Some(fuzz) = fuzz {
+                input.insert("fuzz".to_string(), json!(fuzz));
+            }
+
+            let result = tool
+                .execute(Value::Object(input), &ctx)
+                .await
+                .expect("execute");
+
+            assert!(result.success, "{file_name}: {}", result.content);
+            assert!(result.content.contains("Replaced 1 occurrence"));
+            let edited = fs::read_to_string(&test_file).expect("read");
+            assert_eq!(edited, "hi world");
+        }
+    }
+
     #[tokio::test]
     async fn test_edit_file_single_match_has_no_multi_match_warning() {
         let tmp = tempdir().expect("tempdir");
@@ -1832,7 +1942,13 @@ mod tests {
             .get("required")
             .and_then(|value| value.as_array())
             .expect("edit schema should include required array");
-        assert_eq!(required.len(), 3);
+        let required_fields: Vec<_> = required.iter().filter_map(|value| value.as_str()).collect();
+        assert_eq!(required_fields, vec!["path", "search", "replace"]);
+        assert!(!required_fields.contains(&"fuzz"));
+        assert_eq!(
+            edit_schema["properties"]["fuzz"]["type"].as_str(),
+            Some("boolean")
+        );
         let search_desc = edit_schema["properties"]["search"]["description"]
             .as_str()
             .expect("search description");
diff --git a/crates/tui/src/tools/goal.rs b/crates/tui/src/tools/goal.rs
new file mode 100644
index 00000000..5ce3c4d1
--- /dev/null
+++ b/crates/tui/src/tools/goal.rs
@@ -0,0 +1,559 @@
+//! Goal tools for the model-visible LLM-as-judge loop.
+//!
+//! The TUI already has a `/goal` command and passes its objective into the
+//! engine prompt. This module keeps the runtime slice separate: a small
+//! session-scoped state object plus tools the model can use to inspect and
+//! close out that state.
+
+use std::sync::{Arc, Mutex};
+use std::time::Instant;
+
+use async_trait::async_trait;
+use serde::Serialize;
+use serde_json::{Value, json};
+
+use crate::tools::spec::{
+    ApprovalRequirement, ToolCapability, ToolContext, ToolError, ToolResult, ToolSpec, required_str,
+};
+
+/// Maximum number of automatic goal-continuation prompt injections in one
+/// engine turn. This prevents a missing `update_goal` call from becoming an
+/// unbounded local loop.
+pub const MAX_GOAL_CONTINUATIONS_PER_TURN: u32 = 3;
+
+/// Shared reference to the current runtime goal.
+pub type SharedGoalState = Arc<Mutex<GoalState>>;
+
+/// Create an empty shared goal state.
+#[must_use]
+pub fn new_shared_goal_state() -> SharedGoalState {
+    Arc::new(Mutex::new(GoalState::default()))
+}
+
+/// Create shared state seeded from the existing `/goal` surface.
+#[must_use]
+pub fn new_shared_goal_state_from_host(
+    objective: Option<String>,
+    token_budget: Option<u32>,
+    completed: bool,
+) -> SharedGoalState {
+    let mut state = GoalState::default();
+    state.sync_from_host(objective.as_deref(), token_budget, completed);
+    Arc::new(Mutex::new(state))
+}
+
+/// Runtime status for a goal.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum GoalStatus {
+    Active,
+    Complete,
+    Blocked,
+}
+
+impl GoalStatus {
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Complete => "complete",
+            Self::Blocked => "blocked",
+        }
+    }
+}
+
+/// Session-local goal state. `Instant` stays runtime-only; snapshots expose
+/// elapsed seconds so tool output remains serializable and stable.
+#[derive(Debug, Clone, Default)]
+pub struct GoalState {
+    objective: Option<String>,
+    token_budget: Option<u32>,
+    status: Option<GoalStatus>,
+    started_at: Option<Instant>,
+    finished_at: Option<Instant>,
+    evidence: Option<String>,
+    blocker: Option<String>,
+}
+
+impl GoalState {
+    #[must_use]
+    pub fn objective(&self) -> Option<&str> {
+        self.objective.as_deref()
+    }
+
+    #[must_use]
+    pub fn is_active(&self) -> bool {
+        self.objective.is_some() && self.status == Some(GoalStatus::Active)
+    }
+
+    pub fn sync_from_host(
+        &mut self,
+        objective: Option<&str>,
+        token_budget: Option<u32>,
+        completed: bool,
+    ) {
+        let objective = objective.map(str::trim).filter(|value| !value.is_empty());
+        match objective {
+            Some(objective) => {
+                let changed = self.objective.as_deref() != Some(objective);
+                if changed {
+                    self.objective = Some(objective.to_string());
+                    self.token_budget = token_budget;
+                    self.started_at = Some(Instant::now());
+                    self.evidence = None;
+                    self.blocker = None;
+                } else if token_budget.is_some() {
+                    self.token_budget = token_budget;
+                }
+
+                if changed || self.status.is_none() {
+                    self.status = Some(if completed {
+                        GoalStatus::Complete
+                    } else {
+                        GoalStatus::Active
+                    });
+                    self.finished_at = completed.then(Instant::now);
+                }
+            }
+            None => self.clear(),
+        }
+    }
+
+    pub fn create(&mut self, objective: String, token_budget: Option<u32>) {
+        self.objective = Some(objective);
+        self.token_budget = token_budget;
+        self.status = Some(GoalStatus::Active);
+        self.started_at = Some(Instant::now());
+        self.finished_at = None;
+        self.evidence = None;
+        self.blocker = None;
+    }
+
+    pub fn resume(&mut self, objective: Option<String>) -> Result<(), &'static str> {
+        if let Some(objective) = objective {
+            self.create(objective, self.token_budget);
+            return Ok(());
+        }
+        if self.objective.is_none() {
+            return Err("No goal exists to resume.");
+        }
+        self.status = Some(GoalStatus::Active);
+        self.finished_at = None;
+        self.evidence = None;
+        self.blocker = None;
+        Ok(())
+    }
+
+    pub fn mark_complete(&mut self, evidence: String) -> Result<(), &'static str> {
+        if self.objective.is_none() {
+            return Err("No active goal exists to complete.");
+        }
+        self.status = Some(GoalStatus::Complete);
+        self.finished_at = Some(Instant::now());
+        self.evidence = Some(evidence);
+        self.blocker = None;
+        Ok(())
+    }
+
+    pub fn mark_blocked(&mut self, blocker: String) -> Result<(), &'static str> {
+        if self.objective.is_none() {
+            return Err("No active goal exists to block.");
+        }
+        self.status = Some(GoalStatus::Blocked);
+        self.finished_at = Some(Instant::now());
+        self.blocker = Some(blocker);
+        Ok(())
+    }
+
+    pub fn clear(&mut self) {
+        *self = Self::default();
+    }
+
+    #[must_use]
+    pub fn snapshot(&self) -> GoalSnapshot {
+        GoalSnapshot {
+            objective: self.objective.clone(),
+            status: self
+                .status
+                .map(GoalStatus::as_str)
+                .unwrap_or("none")
+                .to_string(),
+            token_budget: self.token_budget,
+            elapsed_seconds: self.started_at.map(|started| started.elapsed().as_secs()),
+            evidence: self.evidence.clone(),
+            blocker: self.blocker.clone(),
+        }
+    }
+}
+
+/// Serializable tool output and prompt input for the current goal.
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct GoalSnapshot {
+    pub objective: Option<String>,
+    pub status: String,
+    pub token_budget: Option<u32>,
+    pub elapsed_seconds: Option<u64>,
+    pub evidence: Option<String>,
+    pub blocker: Option<String>,
+}
+
+impl GoalSnapshot {
+    #[must_use]
+    pub fn is_active(&self) -> bool {
+        self.objective.is_some() && self.status == GoalStatus::Active.as_str()
+    }
+}
+
+/// Render the bounded continuation prompt injected when a goal is still active
+/// after an assistant message has no tool calls.
+#[must_use]
+pub fn render_continuation_prompt(
+    snapshot: &GoalSnapshot,
+    continuation_index: u32,
+    max_continuations: u32,
+) -> String {
+    let goal_json = serde_json::to_string_pretty(snapshot).unwrap_or_else(|_| "{}".to_string());
+    format!(
+        "{}\n\n## Active Goal State\n\n```json\n{}\n```\n\nContinuation pass: {}/{}.\nIf the goal is complete, call `update_goal` with `status: \"complete\"` and concrete evidence. If it is blocked, call `update_goal` with `status: \"blocked\"` and the blocker. Otherwise continue making progress toward the objective.",
+        crate::prompts::GOAL_CONTINUATION_PROMPT.trim(),
+        goal_json,
+        continuation_index,
+        max_continuations,
+    )
+}
+
+fn lock_goal_state(
+    state: &SharedGoalState,
+) -> Result<std::sync::MutexGuard<'_, GoalState>, ToolError> {
+    state
+        .lock()
+        .map_err(|_| ToolError::execution_failed("goal state lock poisoned"))
+}
+
+fn parse_token_budget(input: &Value) -> Result<Option<u32>, ToolError> {
+    let Some(raw) = input.get("token_budget") else {
+        return Ok(None);
+    };
+    if raw.is_null() {
+        return Ok(None);
+    }
+    let Some(value) = raw.as_u64() else {
+        return Err(ToolError::invalid_input(
+            "token_budget must be a non-negative integer",
+        ));
+    };
+    u32::try_from(value)
+        .map(Some)
+        .map_err(|_| ToolError::invalid_input("token_budget is too large"))
+}
+
+fn json_result(snapshot: &GoalSnapshot) -> Result<ToolResult, ToolError> {
+    ToolResult::json(snapshot).map_err(|err| ToolError::execution_failed(err.to_string()))
+}
+
+pub struct CreateGoalTool {
+    goal_state: SharedGoalState,
+}
+
+impl CreateGoalTool {
+    #[must_use]
+    pub fn new(goal_state: SharedGoalState) -> Self {
+        Self { goal_state }
+    }
+}
+
+#[async_trait]
+impl ToolSpec for CreateGoalTool {
+    fn name(&self) -> &'static str {
+        "create_goal"
+    }
+
+    fn description(&self) -> &'static str {
+        "Create or replace the current runtime goal. Use this when the user asks for a persistent goal that should be audited before the turn is allowed to finish."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "objective": {
+                    "type": "string",
+                    "description": "The full objective to pursue. Keep the complete user goal, not a shortened one-turn version."
+                },
+                "token_budget": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Optional soft token budget for the goal."
+                }
+            },
+            "required": ["objective"],
+            "additionalProperties": false
+        })
+    }
+
+    fn capabilities(&self) -> Vec<ToolCapability> {
+        Vec::new()
+    }
+
+    fn approval_requirement(&self) -> ApprovalRequirement {
+        ApprovalRequirement::Auto
+    }
+
+    async fn execute(&self, input: Value, _context: &ToolContext) -> Result<ToolResult, ToolError> {
+        let objective = required_str(&input, "objective")?.trim().to_string();
+        if objective.is_empty() {
+            return Err(ToolError::invalid_input("objective cannot be empty"));
+        }
+        let token_budget = parse_token_budget(&input)?;
+        let snapshot = {
+            let mut state = lock_goal_state(&self.goal_state)?;
+            state.create(objective, token_budget);
+            state.snapshot()
+        };
+        json_result(&snapshot)
+    }
+}
+
+pub struct GetGoalTool {
+    goal_state: SharedGoalState,
+}
+
+impl GetGoalTool {
+    #[must_use]
+    pub fn new(goal_state: SharedGoalState) -> Self {
+        Self { goal_state }
+    }
+}
+
+#[async_trait]
+impl ToolSpec for GetGoalTool {
+    fn name(&self) -> &'static str {
+        "get_goal"
+    }
+
+    fn description(&self) -> &'static str {
+        "Inspect the current runtime goal state, including objective, status, token budget, elapsed time, evidence, and blocker."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        })
+    }
+
+    fn capabilities(&self) -> Vec<ToolCapability> {
+        vec![ToolCapability::ReadOnly]
+    }
+
+    fn approval_requirement(&self) -> ApprovalRequirement {
+        ApprovalRequirement::Auto
+    }
+
+    fn supports_parallel(&self) -> bool {
+        true
+    }
+
+    async fn execute(
+        &self,
+        _input: Value,
+        _context: &ToolContext,
+    ) -> Result<ToolResult, ToolError> {
+        let snapshot = {
+            let state = lock_goal_state(&self.goal_state)?;
+            state.snapshot()
+        };
+        json_result(&snapshot)
+    }
+}
+
+pub struct UpdateGoalTool {
+    goal_state: SharedGoalState,
+}
+
+impl UpdateGoalTool {
+    #[must_use]
+    pub fn new(goal_state: SharedGoalState) -> Self {
+        Self { goal_state }
+    }
+}
+
+#[async_trait]
+impl ToolSpec for UpdateGoalTool {
+    fn name(&self) -> &'static str {
+        "update_goal"
+    }
+
+    fn description(&self) -> &'static str {
+        "Update the runtime goal. This is the LLM-as-judge completion gate: only mark complete when the objective has been verified against concrete current-state evidence."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "enum": ["active", "complete", "blocked"],
+                    "description": "Use complete only when the goal is fully satisfied; blocked when meaningful progress cannot continue; active to resume or revise the objective."
+                },
+                "evidence": {
+                    "type": "string",
+                    "description": "Required when status is complete. Briefly cite the proof that the goal is done."
+                },
+                "blocker": {
+                    "type": "string",
+                    "description": "Required when status is blocked. Explain the condition preventing progress."
+                },
+                "objective": {
+                    "type": "string",
+                    "description": "Optional replacement objective when status is active."
+                }
+            },
+            "required": ["status"],
+            "additionalProperties": false
+        })
+    }
+
+    fn capabilities(&self) -> Vec<ToolCapability> {
+        Vec::new()
+    }
+
+    fn approval_requirement(&self) -> ApprovalRequirement {
+        ApprovalRequirement::Auto
+    }
+
+    async fn execute(&self, input: Value, _context: &ToolContext) -> Result<ToolResult, ToolError> {
+        let status = required_str(&input, "status")?.trim().to_ascii_lowercase();
+        let snapshot = {
+            let mut state = lock_goal_state(&self.goal_state)?;
+            match status.as_str() {
+                "complete" => {
+                    let evidence = input
+                        .get("evidence")
+                        .and_then(Value::as_str)
+                        .map(str::trim)
+                        .unwrap_or_default()
+                        .to_string();
+                    if evidence.is_empty() {
+                        return Err(ToolError::invalid_input(
+                            "evidence is required when status is complete",
+                        ));
+                    }
+                    state
+                        .mark_complete(evidence)
+                        .map_err(ToolError::invalid_input)?;
+                }
+                "blocked" => {
+                    let blocker = input
+                        .get("blocker")
+                        .and_then(Value::as_str)
+                        .map(str::trim)
+                        .unwrap_or_default()
+                        .to_string();
+                    if blocker.is_empty() {
+                        return Err(ToolError::invalid_input(
+                            "blocker is required when status is blocked",
+                        ));
+                    }
+                    state
+                        .mark_blocked(blocker)
+                        .map_err(ToolError::invalid_input)?;
+                }
+                "active" => {
+                    let objective = input
+                        .get("objective")
+                        .and_then(Value::as_str)
+                        .map(str::trim)
+                        .filter(|value| !value.is_empty())
+                        .map(str::to_string);
+                    state.resume(objective).map_err(ToolError::invalid_input)?;
+                }
+                other => {
+                    return Err(ToolError::invalid_input(format!(
+                        "unsupported goal status '{other}'"
+                    )));
+                }
+            }
+            state.snapshot()
+        };
+        json_result(&snapshot)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::*;
+
+    #[tokio::test]
+    async fn create_get_and_complete_goal() {
+        let state = new_shared_goal_state();
+        let ctx = ToolContext::new(".");
+
+        let create = CreateGoalTool::new(state.clone());
+        let created = create
+            .execute(
+                json!({
+                    "objective": "ship the runtime slice",
+                    "token_budget": 1200
+                }),
+                &ctx,
+            )
+            .await
+            .expect("create goal");
+        assert!(created.success);
+        assert!(created.content.contains("\"status\": \"active\""));
+
+        let get = GetGoalTool::new(state.clone());
+        let current = get.execute(json!({}), &ctx).await.expect("get goal");
+        assert!(current.content.contains("ship the runtime slice"));
+        assert!(current.content.contains("\"token_budget\": 1200"));
+
+        let update = UpdateGoalTool::new(state.clone());
+        let completed = update
+            .execute(
+                json!({
+                    "status": "complete",
+                    "evidence": "focused tests passed"
+                }),
+                &ctx,
+            )
+            .await
+            .expect("complete goal");
+        assert!(completed.content.contains("\"status\": \"complete\""));
+        assert!(completed.content.contains("focused tests passed"));
+        assert!(!state.lock().expect("goal lock").is_active());
+    }
+
+    #[tokio::test]
+    async fn update_goal_requires_completion_evidence() {
+        let state =
+            new_shared_goal_state_from_host(Some("prove completion".to_string()), None, false);
+        let update = UpdateGoalTool::new(state);
+        let err = update
+            .execute(json!({"status": "complete"}), &ToolContext::new("."))
+            .await
+            .expect_err("missing evidence should fail");
+
+        assert!(err.to_string().contains("evidence is required"));
+    }
+
+    #[test]
+    fn continuation_prompt_includes_bound_and_goal_state() {
+        let snapshot = GoalSnapshot {
+            objective: Some("finish issue 2199".to_string()),
+            status: "active".to_string(),
+            token_budget: None,
+            elapsed_seconds: Some(5),
+            evidence: None,
+            blocker: None,
+        };
+
+        let prompt = render_continuation_prompt(&snapshot, 2, 3);
+        assert!(prompt.contains("Goal Continuation"));
+        assert!(prompt.contains("finish issue 2199"));
+        assert!(prompt.contains("Continuation pass: 2/3"));
+    }
+}
diff --git a/crates/tui/src/tools/mod.rs b/crates/tui/src/tools/mod.rs
index 1a6d470f..e5427065 100644
--- a/crates/tui/src/tools/mod.rs
+++ b/crates/tui/src/tools/mod.rs
@@ -12,6 +12,7 @@ pub mod apply_patch;
 pub mod approval_cache;
 pub mod arg_repair;
 pub mod automation;
+pub mod cargo_failure_summary;
 pub mod diagnostics;
 pub mod diff_format;
 pub mod file;
@@ -23,6 +24,7 @@ pub mod fim;
 pub mod git;
 pub mod git_history;
 pub mod github;
+pub mod goal;
 pub mod handle;
 pub mod image_ocr;
 pub mod js_execution;
diff --git a/crates/tui/src/tools/recall_archive.rs b/crates/tui/src/tools/recall_archive.rs
index 380d11ad..6ec0b1a6 100644
--- a/crates/tui/src/tools/recall_archive.rs
+++ b/crates/tui/src/tools/recall_archive.rs
@@ -162,11 +162,10 @@ fn archive_root(session_id: &str) -> Result<PathBuf, std::io::Error> {
             "Could not resolve home directory for cycle archive root",
         )
     })?;
-    Ok(home
-        .join(".deepseek")
-        .join("sessions")
-        .join(session_id)
-        .join("cycles"))
+    // Use resolved sessions dir (prefers ~/.codewhale/sessions)
+    let sessions = codewhale_config::resolve_state_dir("sessions")
+        .unwrap_or_else(|_| home.join(".deepseek").join("sessions"));
+    Ok(sessions.join(session_id).join("cycles"))
 }
 
 /// Enumerate all archive files for a session, sorted by cycle number ascending.
diff --git a/crates/tui/src/tools/registry.rs b/crates/tui/src/tools/registry.rs
index 5254de70..2e3d09c9 100644
--- a/crates/tui/src/tools/registry.rs
+++ b/crates/tui/src/tools/registry.rs
@@ -542,6 +542,10 @@ impl ToolRegistryBuilder {
     }
 
     /// Include durable task, gate, PR-attempt, GitHub, and automation tools.
+    ///
+    /// Shell-related task tools (`task_shell_start`, `task_shell_wait`) are
+    /// *not* included here — use [`with_runtime_task_shell_tools`] to register
+    /// them when `allow_shell` is true.
     #[must_use]
     pub fn with_runtime_task_tools(self) -> Self {
         use super::automation::{
@@ -555,7 +559,6 @@ impl ToolRegistryBuilder {
         use super::tasks::{
             PrAttemptListTool, PrAttemptPreflightTool, PrAttemptReadTool, PrAttemptRecordTool,
             TaskCancelTool, TaskCreateTool, TaskGateRunTool, TaskListTool, TaskReadTool,
-            TaskShellStartTool, TaskShellWaitTool,
         };
 
         self.with_tool(Arc::new(TaskCreateTool))
@@ -563,8 +566,6 @@ impl ToolRegistryBuilder {
             .with_tool(Arc::new(TaskReadTool))
             .with_tool(Arc::new(TaskCancelTool))
             .with_tool(Arc::new(TaskGateRunTool))
-            .with_tool(Arc::new(TaskShellStartTool))
-            .with_tool(Arc::new(TaskShellWaitTool))
             .with_tool(Arc::new(GithubIssueContextTool))
             .with_tool(Arc::new(GithubPrContextTool))
             .with_tool(Arc::new(PrAttemptRecordTool))
@@ -584,6 +585,18 @@ impl ToolRegistryBuilder {
             .with_tool(Arc::new(GithubClosePrTool))
     }
 
+    /// Include shell-related task tools (`task_shell_start`, `task_shell_wait`).
+    ///
+    /// These are gated behind `allow_shell` because `task_shell_start`
+    /// delegates directly to `ExecShellTool`, providing the same shell
+    /// execution capability as `exec_shell`.
+    #[must_use]
+    pub fn with_runtime_task_shell_tools(self) -> Self {
+        use super::tasks::{TaskShellStartTool, TaskShellWaitTool};
+        self.with_tool(Arc::new(TaskShellStartTool))
+            .with_tool(Arc::new(TaskShellWaitTool))
+    }
+
     /// Include only read-only durable task, PR-attempt, GitHub, and automation
     /// inspection tools. Plan mode uses this surface so it can observe state
     /// without starting work, changing remotes, or mutating automation config.
@@ -720,6 +733,30 @@ impl ToolRegistryBuilder {
         self.with_tool(Arc::new(RememberTool))
     }
 
+    /// Include the slop ledger tools (#2127) — durable tracking of
+    /// unresolved architectural residue: append, query, update, export.
+    /// Registered unconditionally; the ledger JSON file is auto-created
+    /// on first append.
+    #[must_use]
+    pub fn with_slop_ledger_tools(self) -> Self {
+        use crate::slop_ledger::{
+            SlopLedgerAppendTool, SlopLedgerExportTool, SlopLedgerQueryTool, SlopLedgerUpdateTool,
+        };
+        self.with_tool(Arc::new(SlopLedgerAppendTool))
+            .with_tool(Arc::new(SlopLedgerQueryTool))
+            .with_tool(Arc::new(SlopLedgerUpdateTool))
+            .with_tool(Arc::new(SlopLedgerExportTool))
+    }
+
+    /// Read-only subset of slop ledger tools (#2127) for plan mode:
+    /// only query and export — no append or update.
+    #[must_use]
+    pub fn with_slop_ledger_read_only_tools(self) -> Self {
+        use crate::slop_ledger::{SlopLedgerExportTool, SlopLedgerQueryTool};
+        self.with_tool(Arc::new(SlopLedgerQueryTool))
+            .with_tool(Arc::new(SlopLedgerExportTool))
+    }
+
     /// Include the `notify` tool — model-callable desktop notification
     /// (#1322). Routes through the existing `tui::notifications` OSC 9 /
     /// BEL pipeline so the user's `[notifications].method` config is
@@ -786,7 +823,7 @@ impl ToolRegistryBuilder {
             .with_image_ocr_tools();
 
         if allow_shell {
-            builder.with_shell_tools()
+            builder.with_shell_tools().with_runtime_task_shell_tools()
         } else {
             builder
         }
@@ -844,6 +881,15 @@ impl ToolRegistryBuilder {
         self.with_tool(Arc::new(UpdatePlanTool::new(plan_state)))
     }
 
+    /// Include runtime goal tools (`create_goal`, `get_goal`, `update_goal`).
+    #[must_use]
+    pub fn with_goal_tools(self, goal_state: super::goal::SharedGoalState) -> Self {
+        use super::goal::{CreateGoalTool, GetGoalTool, UpdateGoalTool};
+        self.with_tool(Arc::new(CreateGoalTool::new(goal_state.clone())))
+            .with_tool(Arc::new(GetGoalTool::new(goal_state.clone())))
+            .with_tool(Arc::new(UpdateGoalTool::new(goal_state)))
+    }
+
     /// Include sub-agent management tools.
     #[must_use]
     pub fn with_subagent_tools(
@@ -1370,4 +1416,48 @@ mod tests {
 
         assert!(registry.contains("finance"));
     }
+
+    #[test]
+    fn agent_tools_with_allow_shell_false_excludes_shell_tools() {
+        let tmp = tempdir().expect("tempdir");
+        let ctx = ToolContext::new(tmp.path().to_path_buf());
+
+        let registry = ToolRegistryBuilder::new()
+            .with_agent_tools(false)
+            .build(ctx);
+
+        assert!(
+            !registry.contains("exec_shell"),
+            "exec_shell should be excluded when allow_shell is false"
+        );
+        assert!(
+            !registry.contains("task_shell_start"),
+            "task_shell_start should be excluded when allow_shell is false"
+        );
+        assert!(
+            !registry.contains("task_shell_wait"),
+            "task_shell_wait should be excluded when allow_shell is false"
+        );
+    }
+
+    #[test]
+    fn agent_tools_with_allow_shell_true_includes_shell_tools() {
+        let tmp = tempdir().expect("tempdir");
+        let ctx = ToolContext::new(tmp.path().to_path_buf());
+
+        let registry = ToolRegistryBuilder::new().with_agent_tools(true).build(ctx);
+
+        assert!(
+            registry.contains("exec_shell"),
+            "exec_shell should be included when allow_shell is true"
+        );
+        assert!(
+            registry.contains("task_shell_start"),
+            "task_shell_start should be included when allow_shell is true"
+        );
+        assert!(
+            registry.contains("task_shell_wait"),
+            "task_shell_wait should be included when allow_shell is true"
+        );
+    }
 }
diff --git a/crates/tui/src/tools/rlm.rs b/crates/tui/src/tools/rlm.rs
index 36ae09b6..4133cc49 100644
--- a/crates/tui/src/tools/rlm.rs
+++ b/crates/tui/src/tools/rlm.rs
@@ -27,6 +27,11 @@ const DEFAULT_CHILD_MODEL: &str = "deepseek-v4-flash";
 const MAX_INLINE_CONTENT_CHARS: usize = 200_000;
 const FULL_STDOUT_HEAD_CHARS: usize = 4_096;
 const FULL_STDOUT_TAIL_CHARS: usize = 1_024;
+
+/// When `rlm_eval` stdout exceeds this many characters the full body is
+/// stored as a `var_handle` instead of inlined into the parent transcript.
+/// The model retrieves the body via `handle_read` using the returned handle.
+const STDOUT_HANDLE_THRESHOLD_CHARS: usize = 1_000;
 const HARD_SUB_RLM_DEPTH_CAP: u32 = 3;
 
 pub struct RlmSessionObjectsTool;
@@ -217,8 +222,11 @@ impl ToolSpec for RlmEvalTool {
          bounded projection of stdout/stderr plus metadata. If the code calls \
          FINAL/finalize, the final value is stored as a var_handle retrievable \
          with handle_read instead of copied unbounded into the parent context. \
-         Batch child helpers require dependency_mode='independent'; use \
-         sub_query_sequence or a sequential loop for dependent work."
+         Large stdout/stderr payloads (>1k chars) are also stored as \
+         var_handles (returned in stdout_handle / stderr_handle) to keep the \
+         parent transcript lean. Batch child helpers require \
+         dependency_mode='independent'; use sub_query_sequence or a \
+         sequential loop for dependent work."
     }
 
     fn input_schema(&self) -> Value {
@@ -299,14 +307,48 @@ impl ToolSpec for RlmEvalTool {
         let had_error = round.has_error;
         let rpc_count = round.rpc_count;
         let duration_ms = round.elapsed.as_millis() as u64;
-        let stdout_preview = match config.output_feedback {
-            OutputFeedback::Full => Some(preview_output(&round.full_stdout)),
-            OutputFeedback::Metadata => None,
-        };
-        let stderr_preview = match config.output_feedback {
-            OutputFeedback::Full if !round.stderr.is_empty() => Some(preview_output(&round.stderr)),
-            _ => None,
-        };
+        // Route large stdout/stderr into a var_handle to avoid bloat in
+        // the parent transcript. The model calls handle_read for bounded
+        // projections; a short inline note describes availability.
+        fn route_output(
+            text: &str,
+            feedback: &OutputFeedback,
+            store: &mut crate::tools::handle::HandleStore,
+            session_id: &str,
+            tag: &str,
+        ) -> (Option<String>, Option<crate::tools::handle::VarHandle>) {
+            let threshold = STDOUT_HANDLE_THRESHOLD_CHARS;
+            match (feedback, text.len()) {
+                (OutputFeedback::Full, len) if len <= threshold => {
+                    (Some(preview_output(text)), None)
+                }
+                (OutputFeedback::Full, _) if !text.trim().is_empty() => {
+                    // Store full body as a handle for out-of-band retrieval
+                    let name = format!("{tag}_{}", 0); // single counter is fine
+                    let handle = store.insert_text(session_id, name, text);
+                    (
+                        Some(format!("{} chars; retrieve via handle_read", text.len())),
+                        Some(handle),
+                    )
+                }
+                _ => (None, None),
+            }
+        }
+
+        let (stdout_preview, stdout_handle) = route_output(
+            &round.full_stdout,
+            &config.output_feedback,
+            &mut *context.runtime.handle_store.lock().await,
+            &session.id,
+            "stdout",
+        );
+        let (stderr_preview, stderr_handle) = route_output(
+            &round.stderr,
+            &config.output_feedback,
+            &mut *context.runtime.handle_store.lock().await,
+            &session.id,
+            "stderr",
+        );
 
         let mut output = json!({
             "name": session.name,
@@ -317,12 +359,18 @@ impl ToolSpec for RlmEvalTool {
             "new_vars": [],
             "final": final_handle,
         });
-        if let Some(stdout_preview) = stdout_preview {
+        if let Some(ref stdout_preview) = stdout_preview {
             output["stdout_preview"] = json!(stdout_preview);
         }
-        if let Some(stderr_preview) = stderr_preview {
+        if let Some(ref stderr_preview) = stderr_preview {
             output["stderr_preview"] = json!(stderr_preview);
         }
+        if let (Some(h), Some(_)) = (stdout_handle, &stdout_preview) {
+            output["stdout_handle"] = json!(h);
+        }
+        if let (Some(h), Some(_)) = (stderr_handle, &stderr_preview) {
+            output["stderr_handle"] = json!(h);
+        }
         if let Some(confidence) = round.final_confidence.clone() {
             output["confidence"] = confidence;
         }
diff --git a/crates/tui/src/tools/search.rs b/crates/tui/src/tools/search.rs
index b4fc8d1f..221d760b 100644
--- a/crates/tui/src/tools/search.rs
+++ b/crates/tui/src/tools/search.rs
@@ -13,6 +13,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 use std::fs;
 use std::path::{Path, PathBuf};
+use std::time::Duration;
 use tokio_util::sync::CancellationToken;
 
 /// Maximum number of results to return to avoid overwhelming output
@@ -21,6 +22,11 @@ const MAX_RESULTS: usize = 100;
 /// Maximum file size to search (skip large binaries)
 const MAX_FILE_SIZE: u64 = 10 * 1024 * 1024; // 10MB
 
+/// Hard cap on a single grep_files run. The directory walk plus per-file regex
+/// is synchronous blocking work; without this it can run for minutes on a large
+/// tree. Mirrors the file_search tool so both blocking searches behave the same.
+const GREP_FILES_TIMEOUT: Duration = Duration::from_secs(30);
+
 /// Result of a grep match
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct GrepMatch {
@@ -115,17 +121,28 @@ impl ToolSpec for GrepFilesTool {
         let exclude_patterns: Vec<String> =
             input.get("exclude").and_then(|v| v.as_array()).map_or_else(
                 || {
-                    // Default exclusions for common non-code directories
+                    // Default exclusions for common non-code directories.
+                    // Bare directory names skip the directory traversal entirely;
+                    // `dir/*` filters files inside if the directory is already
+                    // being walked (belt-and-suspenders — see #2200).
                     vec![
+                        "node_modules".to_string(),
                         "node_modules/*".to_string(),
+                        ".git".to_string(),
                         ".git/*".to_string(),
+                        "target".to_string(),
                         "target/*".to_string(),
                         "*.min.js".to_string(),
                         "*.min.css".to_string(),
+                        "dist".to_string(),
                         "dist/*".to_string(),
+                        "build".to_string(),
                         "build/*".to_string(),
+                        "__pycache__".to_string(),
                         "__pycache__/*".to_string(),
+                        ".venv".to_string(),
                         ".venv/*".to_string(),
+                        "venv".to_string(),
                         "venv/*".to_string(),
                     ]
                 },
@@ -149,101 +166,155 @@ impl ToolSpec for GrepFilesTool {
         // Resolve search path
         let search_path = context.resolve_path(path_str)?;
 
-        let cancel_token = context.cancel_token.as_ref();
+        let workspace = context.workspace.clone();
+        let cancel_token = context.cancel_token.clone();
 
-        // Collect files to search
-        let files = collect_files(
-            &search_path,
-            &include_patterns,
-            &exclude_patterns,
-            cancel_token,
-        )?;
+        // The directory walk and per-file regex are synchronous blocking work.
+        // Run them on a blocking worker bounded by a hard timeout so a huge tree
+        // can't pin the async runtime and leave the stop button unresponsive.
+        let result = run_blocking_grep(GREP_FILES_TIMEOUT, cancel_token.clone(), move || {
+            let cancel_token = cancel_token.as_ref();
 
-        // Search files
-        let mut results: Vec<GrepMatch> = Vec::new();
-        let mut files_searched = 0;
-        let mut total_matches = 0;
+            // Collect files to search
+            let files = collect_files(
+                &search_path,
+                &include_patterns,
+                &exclude_patterns,
+                cancel_token,
+            )?;
 
-        for file_path in files {
-            check_cancelled(cancel_token)?;
+            // Search files
+            let mut results: Vec<GrepMatch> = Vec::new();
+            let mut files_searched = 0;
+            let mut total_matches = 0;
 
-            if results.len() >= max_results {
-                break;
-            }
-
-            // Skip files that are too large
-            if let Ok(metadata) = fs::metadata(&file_path)
-                && metadata.len() > MAX_FILE_SIZE
-            {
-                continue;
-            }
-
-            // Read file content
-            let Ok(file_content) = fs::read_to_string(&file_path) else {
-                continue; // Skip binary or unreadable files
-            };
-
-            files_searched += 1;
-            let lines: Vec<&str> = file_content.lines().collect();
-
-            for (line_idx, line) in lines.iter().enumerate() {
+            for file_path in files {
                 check_cancelled(cancel_token)?;
 
-                if regex.is_match(line) {
-                    total_matches += 1;
+                if results.len() >= max_results {
+                    break;
+                }
 
-                    // Get context lines
-                    let context_before: Vec<String> = (line_idx.saturating_sub(context_lines)
-                        ..line_idx)
-                        .filter_map(|i| lines.get(i).map(|s| (*s).to_string()))
-                        .collect();
+                // Skip files that are too large
+                if let Ok(metadata) = fs::metadata(&file_path)
+                    && metadata.len() > MAX_FILE_SIZE
+                {
+                    continue;
+                }
 
-                    let context_after: Vec<String> = ((line_idx + 1)
-                        ..=(line_idx + context_lines).min(lines.len() - 1))
-                        .filter_map(|i| lines.get(i).map(|s| (*s).to_string()))
-                        .collect();
+                // Read file content
+                let Ok(file_content) = fs::read_to_string(&file_path) else {
+                    continue; // Skip binary or unreadable files
+                };
 
-                    // Get relative path from workspace
-                    let relative_path = file_path
-                        .strip_prefix(&context.workspace)
-                        .unwrap_or(&file_path)
-                        .to_string_lossy()
-                        .to_string();
+                files_searched += 1;
+                let lines: Vec<&str> = file_content.lines().collect();
 
-                    results.push(GrepMatch {
-                        file: relative_path,
-                        line_number: line_idx + 1,
-                        line: (*line).to_string(),
-                        context_before,
-                        context_after,
-                    });
+                for (line_idx, line) in lines.iter().enumerate() {
+                    check_cancelled(cancel_token)?;
 
-                    if results.len() >= max_results {
-                        break;
+                    if regex.is_match(line) {
+                        total_matches += 1;
+
+                        // Get context lines
+                        let context_before: Vec<String> = (line_idx.saturating_sub(context_lines)
+                            ..line_idx)
+                            .filter_map(|i| lines.get(i).map(|s| (*s).to_string()))
+                            .collect();
+
+                        let context_after: Vec<String> = ((line_idx + 1)
+                            ..=(line_idx + context_lines).min(lines.len() - 1))
+                            .filter_map(|i| lines.get(i).map(|s| (*s).to_string()))
+                            .collect();
+
+                        // Get relative path from workspace
+                        let relative_path = file_path
+                            .strip_prefix(&workspace)
+                            .unwrap_or(&file_path)
+                            .to_string_lossy()
+                            .to_string();
+
+                        results.push(GrepMatch {
+                            file: relative_path,
+                            line_number: line_idx + 1,
+                            line: (*line).to_string(),
+                            context_before,
+                            context_after,
+                        });
+
+                        if results.len() >= max_results {
+                            break;
+                        }
                     }
                 }
             }
-        }
 
-        let matches_json: Vec<Value> = results
-            .iter()
-            .map(|item| grep_match_to_json(item, context_lines))
-            .collect();
+            let matches_json: Vec<Value> = results
+                .iter()
+                .map(|item| grep_match_to_json(item, context_lines))
+                .collect();
 
-        // Build result. When context_lines == 1, return the single context
-        // line as a string instead of a one-item array. That keeps the common
-        // "show just the adjacent line" case easy for model callers to read.
-        let result = json!({
-            "matches": matches_json,
-            "total_matches": total_matches,
-            "files_searched": files_searched,
-            "truncated": total_matches > max_results,
-        });
+            // Build result. When context_lines == 1, return the single context
+            // line as a string instead of a one-item array. That keeps the common
+            // "show just the adjacent line" case easy for model callers to read.
+            Ok(json!({
+                "matches": matches_json,
+                "total_matches": total_matches,
+                "files_searched": files_searched,
+                "truncated": total_matches > max_results,
+            }))
+        })
+        .await?;
 
         ToolResult::json(&result).map_err(|e| ToolError::execution_failed(e.to_string()))
     }
 }
 
+/// Run the synchronous grep walk on a blocking worker, cancellable via the
+/// token and bounded by `timeout`. Mirrors `run_blocking_file_search`.
+async fn run_blocking_grep<F>(
+    timeout: Duration,
+    cancel_token: Option<CancellationToken>,
+    search: F,
+) -> Result<Value, ToolError>
+where
+    F: FnOnce() -> Result<Value, ToolError> + Send + 'static,
+{
+    if cancel_token
+        .as_ref()
+        .is_some_and(CancellationToken::is_cancelled)
+    {
+        return Err(grep_cancelled());
+    }
+
+    let task = tokio::task::spawn_blocking(search);
+    let result = match cancel_token {
+        Some(token) => {
+            tokio::select! {
+                biased;
+                () = token.cancelled() => return Err(grep_cancelled()),
+                result = tokio::time::timeout(timeout, task) => result,
+            }
+        }
+        None => tokio::time::timeout(timeout, task).await,
+    };
+
+    let joined = result.map_err(|_| grep_timeout(timeout))?;
+    joined.map_err(|err| {
+        ToolError::execution_failed(format!("grep_files worker failed before completion: {err}"))
+    })?
+}
+
+fn grep_cancelled() -> ToolError {
+    ToolError::execution_failed("grep_files cancelled before completion")
+}
+
+fn grep_timeout(timeout: Duration) -> ToolError {
+    ToolError::Timeout {
+        seconds: timeout.as_secs().max(1),
+    }
+}
+
 fn grep_match_to_json(item: &GrepMatch, context_lines: usize) -> Value {
     if context_lines == 1 {
         json!({
diff --git a/crates/tui/src/tools/shell.rs b/crates/tui/src/tools/shell.rs
index bb393267..2cfae192 100644
--- a/crates/tui/src/tools/shell.rs
+++ b/crates/tui/src/tools/shell.rs
@@ -622,6 +622,15 @@ impl ShellManager {
         &self.sandbox_policy
     }
 
+    /// Enable or disable bubblewrap passthrough (#2184).
+    ///
+    /// When enabled and `/usr/bin/bwrap` is present on Linux, exec_shell
+    /// commands are routed through bubblewrap for filesystem isolation.
+    #[allow(dead_code)] // Wired from EngineConfig in follow-up PR
+    pub fn set_prefer_bwrap(&mut self, prefer: bool) {
+        self.sandbox_manager.set_prefer_bwrap(prefer);
+    }
+
     /// Request that the active foreground shell wait detach and leave its
     /// process running in the background job table.
     pub fn request_foreground_background(&mut self) {
@@ -722,6 +731,9 @@ impl ShellManager {
         policy_override: Option<ExecutionSandboxPolicy>,
         extra_env: HashMap<String, String>,
     ) -> Result<ShellResult> {
+        // Log execution via ShellDispatcher when SHELL_DISPATCHER_LOG is set.
+        crate::shell_dispatcher::ShellDispatcher::log_exec(command);
+
         let work_dir = working_dir.map_or_else(|| self.default_workspace.clone(), PathBuf::from);
 
         // Clamp timeout to max 10 minutes (600000ms)
@@ -785,6 +797,8 @@ impl ShellManager {
         policy_override: Option<ExecutionSandboxPolicy>,
         extra_env: HashMap<String, String>,
     ) -> Result<ShellResult> {
+        crate::shell_dispatcher::ShellDispatcher::log_exec(command);
+
         let work_dir = working_dir.map_or_else(|| self.default_workspace.clone(), PathBuf::from);
 
         let timeout_ms = timeout_ms.clamp(1000, 600_000);
@@ -832,6 +846,26 @@ impl ShellManager {
 
         child_env::apply_to_command(&mut cmd, child_env::string_map_env(&exec_env.env));
 
+        // Disable raw mode before spawn; restore only if raw mode was active
+        // on entry (issue #1690).
+        let raw_mode_was_enabled = crossterm::terminal::is_raw_mode_enabled().unwrap_or(false);
+        if raw_mode_was_enabled {
+            let _ = crossterm::terminal::disable_raw_mode();
+        }
+        struct SyncRawModeGuard {
+            restore: bool,
+        }
+        impl Drop for SyncRawModeGuard {
+            fn drop(&mut self) {
+                if self.restore {
+                    let _ = crossterm::terminal::enable_raw_mode();
+                }
+            }
+        }
+        let _guard = SyncRawModeGuard {
+            restore: raw_mode_was_enabled,
+        };
+
         let mut child = cmd
             .spawn()
             .with_context(|| format!("Failed to execute: {original_command}"))?;
@@ -966,6 +1000,26 @@ impl ShellManager {
         }
         install_parent_death_signal(&mut cmd);
 
+        // Disable raw mode before spawn; restore only if raw mode was active
+        // on entry (issue #1690).
+        let raw_mode_was_enabled = crossterm::terminal::is_raw_mode_enabled().unwrap_or(false);
+        if raw_mode_was_enabled {
+            let _ = crossterm::terminal::disable_raw_mode();
+        }
+        struct InteractiveRawModeGuard {
+            restore: bool,
+        }
+        impl Drop for InteractiveRawModeGuard {
+            fn drop(&mut self) {
+                if self.restore {
+                    let _ = crossterm::terminal::enable_raw_mode();
+                }
+            }
+        }
+        let _guard = InteractiveRawModeGuard {
+            restore: raw_mode_was_enabled,
+        };
+
         child_env::apply_to_command(&mut cmd, child_env::string_map_env(&exec_env.env));
 
         let mut child = cmd
@@ -1496,6 +1550,7 @@ pub fn new_shared_shell_manager(workspace: PathBuf) -> SharedShellManager {
 use crate::command_safety::{SafetyLevel, analyze_command, extract_primary_command};
 use crate::execpolicy::{ExecPolicyDecision, load_default_policy};
 use crate::features::Feature;
+use crate::tools::cargo_failure_summary::summarize_cargo_failure;
 use crate::tools::spec::{
     ApprovalRequirement, ToolCapability, ToolContext, ToolError, ToolResult, ToolSpec,
     optional_bool, optional_u64, required_str,
@@ -1514,6 +1569,18 @@ shell sandbox). Workarounds: (1) run the Docker build from a regular terminal ou
 TUI, or (2) disable BuildKit with DOCKER_BUILDKIT=0 (only works if your Dockerfiles do not \
 use RUN --mount directives).";
 
+fn attach_cargo_failure_summary(
+    metadata: &mut serde_json::Value,
+    command: &str,
+    result: &ShellResult,
+) {
+    if let Some(summary) =
+        summarize_cargo_failure(command, &result.stdout, &result.stderr, result.exit_code)
+    {
+        metadata["cargo_failure_summary"] = summary.to_metadata_value();
+    }
+}
+
 pub(crate) fn looks_like_macos_provenance_failure(result: &ShellResult) -> bool {
     if matches!(result.status, ShellStatus::Completed) && result.exit_code == Some(0) {
         return false;
@@ -1956,7 +2023,7 @@ impl ToolSpec for ExecShellTool {
                 format!("{}\n\nSTDERR:\n{}", result.stdout, result.stderr)
             };
 
-            let metadata = json!({
+            let mut metadata = json!({
                 "exit_code": result.exit_code,
                 "status": format!("{:?}", result.status),
                 "duration_ms": result.duration_ms,
@@ -1978,6 +2045,7 @@ impl ToolSpec for ExecShellTool {
                 "canceled": false,
                 "sandbox_backend": "opensandbox",
             });
+            attach_cargo_failure_summary(&mut metadata, command, &result);
 
             return Ok(ToolResult {
                 content: output,
@@ -2156,6 +2224,7 @@ impl ToolSpec for ExecShellTool {
                 if provenance_hint.is_some() {
                     metadata["macos_provenance_restricted"] = json!(true);
                 }
+                attach_cargo_failure_summary(&mut metadata, command, &result);
 
                 Ok(ToolResult {
                     content: output,
@@ -2230,31 +2299,34 @@ fn build_shell_delta_tool_result(delta: ShellDeltaResult, context: &ToolContext)
         output = format!("{hint}\n\n{output}");
     }
 
+    let mut metadata = json!({
+        "exit_code": result.exit_code,
+        "status": format!("{:?}", result.status),
+        "duration_ms": result.duration_ms,
+        "sandboxed": result.sandboxed,
+        "sandbox_type": result.sandbox_type,
+        "sandbox_denied": result.sandbox_denied,
+        "task_id": result.task_id,
+        "stdout_len": result.stdout_len,
+        "stderr_len": result.stderr_len,
+        "stdout_truncated": result.stdout_truncated,
+        "stderr_truncated": result.stderr_truncated,
+        "stdout_omitted": result.stdout_omitted,
+        "stderr_omitted": result.stderr_omitted,
+        "stdout_total_len": delta.stdout_total_len,
+        "stderr_total_len": delta.stderr_total_len,
+        "summary": summary,
+        "stdout_summary": stdout_summary,
+        "stderr_summary": stderr_summary,
+        "command": delta.command,
+        "stream_delta": true,
+    });
+    attach_cargo_failure_summary(&mut metadata, &delta.command, &result);
+
     let mut tool_result = ToolResult {
         content: output,
         success: matches!(result.status, ShellStatus::Completed | ShellStatus::Running),
-        metadata: Some(json!({
-            "exit_code": result.exit_code,
-            "status": format!("{:?}", result.status),
-            "duration_ms": result.duration_ms,
-            "sandboxed": result.sandboxed,
-            "sandbox_type": result.sandbox_type,
-            "sandbox_denied": result.sandbox_denied,
-            "task_id": result.task_id,
-            "stdout_len": result.stdout_len,
-            "stderr_len": result.stderr_len,
-            "stdout_truncated": result.stdout_truncated,
-            "stderr_truncated": result.stderr_truncated,
-            "stdout_omitted": result.stdout_omitted,
-            "stderr_omitted": result.stderr_omitted,
-            "stdout_total_len": delta.stdout_total_len,
-            "stderr_total_len": delta.stderr_total_len,
-            "summary": summary,
-            "stdout_summary": stdout_summary,
-            "stderr_summary": stderr_summary,
-            "command": delta.command,
-            "stream_delta": true,
-        })),
+        metadata: Some(metadata),
     };
     if let Some(hint) = network_restricted_hint
         && let Some(metadata) = tool_result.metadata.as_mut()
diff --git a/crates/tui/src/tools/shell/tests.rs b/crates/tui/src/tools/shell/tests.rs
index 08b1f42d..7bcd643c 100644
--- a/crates/tui/src/tools/shell/tests.rs
+++ b/crates/tui/src/tools/shell/tests.rs
@@ -21,6 +21,10 @@ fn echo_command(message: &str) -> String {
 }
 
 fn sleep_command(seconds: u64) -> String {
+    let dispatcher = crate::shell_dispatcher::global_dispatcher();
+    if dispatcher.kind().is_powershell() {
+        return format!("Start-Sleep -Seconds {seconds}");
+    }
     #[cfg(windows)]
     {
         let ping_count = seconds.saturating_add(1);
@@ -33,6 +37,10 @@ fn sleep_command(seconds: u64) -> String {
 }
 
 fn sleep_then_echo_command(seconds: u64, message: &str) -> String {
+    let dispatcher = crate::shell_dispatcher::global_dispatcher();
+    if dispatcher.kind().is_powershell() {
+        return format!("Start-Sleep -Seconds {seconds}; echo {message}");
+    }
     #[cfg(windows)]
     {
         let ping_count = seconds.saturating_add(1);
@@ -45,6 +53,10 @@ fn sleep_then_echo_command(seconds: u64, message: &str) -> String {
 }
 
 fn echo_stdin_command() -> String {
+    let dispatcher = crate::shell_dispatcher::global_dispatcher();
+    if dispatcher.kind().is_powershell() {
+        return "[Console]::In.ReadToEnd()".to_string();
+    }
     #[cfg(windows)]
     {
         "more".to_string()
@@ -366,6 +378,97 @@ fn shell_delta_result_surfaces_network_restricted_hint() {
     );
 }
 
+#[test]
+fn shell_delta_result_includes_cargo_failure_summary() {
+    let tmp = tempdir().expect("tempdir");
+    let ctx = ToolContext::new(tmp.path());
+    let result = ShellResult {
+        task_id: None,
+        status: ShellStatus::Failed,
+        exit_code: Some(101),
+        stdout: "running 1 test\ntest tests::fails ... FAILED\n\nfailures:\n\n---- tests::fails stdout ----\nthread 'tests::fails' panicked at src/lib.rs:7:9:\nboom\n\ntest result: FAILED. 0 passed; 1 failed; 0 ignored; finished in 0.00s\n".to_string(),
+        stderr: "error: test failed, to rerun pass `--lib`".to_string(),
+        duration_ms: 12,
+        stdout_len: 0,
+        stderr_len: 0,
+        stdout_omitted: 0,
+        stderr_omitted: 0,
+        stdout_truncated: false,
+        stderr_truncated: false,
+        sandboxed: false,
+        sandbox_type: None,
+        sandbox_denied: false,
+    };
+
+    let tool_result = build_shell_delta_tool_result(
+        ShellDeltaResult {
+            command: "cargo test".to_string(),
+            result,
+            stdout_total_len: 0,
+            stderr_total_len: 0,
+        },
+        &ctx,
+    );
+
+    let metadata = tool_result.metadata.expect("metadata");
+    assert_eq!(
+        metadata["cargo_failure_summary"]["kind"],
+        json!("test_failure")
+    );
+    assert!(
+        metadata["cargo_failure_summary"]["summary"]
+            .as_str()
+            .unwrap()
+            .contains("Failing tests: tests::fails")
+    );
+    assert!(
+        metadata["summary"]
+            .as_str()
+            .unwrap()
+            .contains("error: test failed")
+    );
+}
+
+#[test]
+fn shell_delta_result_keeps_existing_summary_for_generic_cargo_failure() {
+    let tmp = tempdir().expect("tempdir");
+    let ctx = ToolContext::new(tmp.path());
+    let result = ShellResult {
+        task_id: None,
+        status: ShellStatus::Failed,
+        exit_code: Some(1),
+        stdout: "build failed".to_string(),
+        stderr: "command failed without structured cargo diagnostics".to_string(),
+        duration_ms: 12,
+        stdout_len: 0,
+        stderr_len: 0,
+        stdout_omitted: 0,
+        stderr_omitted: 0,
+        stdout_truncated: false,
+        stderr_truncated: false,
+        sandboxed: false,
+        sandbox_type: None,
+        sandbox_denied: false,
+    };
+
+    let tool_result = build_shell_delta_tool_result(
+        ShellDeltaResult {
+            command: "cargo test".to_string(),
+            result,
+            stdout_total_len: 0,
+            stderr_total_len: 0,
+        },
+        &ctx,
+    );
+
+    let metadata = tool_result.metadata.expect("metadata");
+    assert!(metadata.get("cargo_failure_summary").is_none());
+    assert_eq!(
+        metadata["summary"],
+        json!("command failed without structured cargo diagnostics")
+    );
+}
+
 #[test]
 fn test_summarize_output_strips_truncation_note() {
     let long_output = "x".repeat(60_000);
@@ -819,41 +922,48 @@ fn issue_1691_quoted_commit_message_round_trips() {
         Duration::from_secs(5),
     );
 
-    #[cfg(not(windows))]
-    {
-        // `sh -c <cmd>`: the whole command (with quotes) is a single argv
-        // entry. `sh` then POSIX-tokenizes it → correct git argv. We never
-        // split the command string ourselves.
-        assert_eq!(spec.program, "sh");
-        assert_eq!(spec.args, ["-c".to_string(), cmd.to_string()]);
-        assert_eq!(spec.args.len(), 2);
-
-        // push_shell_args is a faithful pass-through on Unix.
-        let mut built = Command::new(&spec.program);
-        push_shell_args(&mut built, &spec.program, &spec.args);
-        let got: Vec<String> = built
-            .get_args()
-            .map(|a| a.to_string_lossy().into_owned())
-            .collect();
-        assert_eq!(got, ["-c".to_string(), cmd.to_string()]);
-    }
-
-    #[cfg(windows)]
-    {
-        // `cmd /C <payload>`: payload carries the quotes verbatim. The fix
-        // routes /C + payload through `raw_arg` so `cmd.exe` (not MSVCRT)
-        // parses it, matching what a terminal does.
-        assert_eq!(spec.program, "cmd");
+    let dispatcher = crate::shell_dispatcher::global_dispatcher();
+    // The whole command (with quotes) is a single argv entry. The actual
+    // shell binary can vary by platform, but the payload itself must stay
+    // intact in one shell arg. We never split the command string ourselves.
+    assert_eq!(spec.program, dispatcher.kind().binary());
+    if dispatcher.kind().is_powershell() {
+        assert_eq!(
+            spec.args,
+            [
+                dispatcher.kind().command_flag().to_string(),
+                "-Command".to_string(),
+                format!("[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; {cmd}")
+            ]
+        );
+    } else if matches!(dispatcher.kind(), crate::shell_dispatcher::ShellKind::Cmd) {
         assert_eq!(
             spec.args,
             ["/C".to_string(), format!("chcp 65001 >NUL & {cmd}")]
         );
-        let mut built = Command::new(&spec.program);
-        push_shell_args(&mut built, &spec.program, &spec.args);
-        let got: Vec<String> = built
-            .get_args()
-            .map(|a| a.to_string_lossy().into_owned())
-            .collect();
-        assert_eq!(got, spec.args);
+    } else {
+        assert_eq!(
+            spec.args,
+            [
+                dispatcher.kind().command_flag().to_string(),
+                cmd.to_string()
+            ]
+        );
     }
+    assert_eq!(
+        spec.args.len(),
+        if dispatcher.kind().is_powershell() {
+            3
+        } else {
+            2
+        }
+    );
+
+    let mut built = Command::new(&spec.program);
+    push_shell_args(&mut built, &spec.program, &spec.args);
+    let got: Vec<String> = built
+        .get_args()
+        .map(|a| a.to_string_lossy().into_owned())
+        .collect();
+    assert_eq!(got, spec.args);
 }
diff --git a/crates/tui/src/tools/spec.rs b/crates/tui/src/tools/spec.rs
index 30a42c49..6a66c37f 100644
--- a/crates/tui/src/tools/spec.rs
+++ b/crates/tui/src/tools/spec.rs
@@ -162,10 +162,12 @@ pub struct ToolContext {
     /// routing (e.g. in sub-agents and test contexts to avoid recursion).
     pub large_output_router: Option<crate::tools::large_output_router::LargeOutputRouter>,
 
-    /// Which search backend `web_search` should use. Default: Bing. Set via
+    /// Which search backend `web_search` should use. Default: DuckDuckGo. Set via
     /// `[search] provider` in config.toml.
     pub search_provider: crate::config::SearchProvider,
-    /// API key for Tavily or Bocha. `None` for Bing or DuckDuckGo.
+    /// API key for Tavily, Bocha, Metaso, or Baidu. `None` for Bing or DuckDuckGo.
+    /// Metaso also falls back to `METASO_API_KEY` env var, then a built-in key.
+    /// Baidu also falls back to `BAIDU_SEARCH_API_KEY`.
     pub search_api_key: Option<String>,
 
     /// Per-session workshop variable store (#548). Holds the raw content of
@@ -182,8 +184,9 @@ impl ToolContext {
     pub fn new(workspace: impl Into<PathBuf>) -> Self {
         let workspace = workspace.into();
         let shell_manager = new_shared_shell_manager(workspace.clone());
-        let notes_path = workspace.join(".deepseek").join("notes.md");
-        let mcp_config_path = workspace.join(".deepseek").join("mcp.json");
+        // Prefer .codewhale, fall back to .deepseek for project-local state
+        let notes_path = codewhale_config::resolve_project_state_dir(&workspace, "notes.md").1;
+        let mcp_config_path = codewhale_config::resolve_project_state_dir(&workspace, "mcp.json").1;
         Self {
             workspace,
             shell_manager,
diff --git a/crates/tui/src/tools/subagent/mod.rs b/crates/tui/src/tools/subagent/mod.rs
index 166de979..cf10a930 100644
--- a/crates/tui/src/tools/subagent/mod.rs
+++ b/crates/tui/src/tools/subagent/mod.rs
@@ -62,7 +62,12 @@ fn release_resident_leases_for(agent_id: &str) {
     }
 }
 
-const DEFAULT_MAX_STEPS: u32 = 100;
+/// Default maximum steps for sub-agent loops. Set to `u32::MAX` to remove the
+/// arbitrary fixed cap (#2034). Sub-agents run until they produce a final text
+/// response (no tool calls), are cancelled by the parent, or hit a configured
+/// explicit budget. Callers that want a hard bound can override `max_steps` on
+/// the `SubAgentManager`.
+const DEFAULT_MAX_STEPS: u32 = u32::MAX;
 const TOOL_TIMEOUT: Duration = Duration::from_secs(30);
 /// Per-step LLM API call timeout. Each `create_message` request must complete
 /// within this window or the step is treated as timed out. Prevents a single
@@ -1840,6 +1845,11 @@ async fn subagent_session_projection(
 }
 
 fn default_state_path(workspace: &Path) -> PathBuf {
+    // Prefer .codewhale, fall back to .deepseek for project-local state
+    let primary = workspace.join(".codewhale").join("state");
+    if primary.exists() {
+        return primary.join(SUBAGENT_STATE_FILE);
+    }
     workspace
         .join(".deepseek")
         .join("state")
@@ -3510,12 +3520,6 @@ async fn run_subagent_task(task: SubAgentTask) {
     )
     .await;
 
-    let mut manager = task.manager_handle.write().await;
-    match &result {
-        Ok(res) => manager.update_from_result(&task.agent_id, res.clone()),
-        Err(err) => manager.update_failed(&task.agent_id, err.to_string()),
-    }
-
     // Emit BOTH a human-friendly summary (rendered in the parent's
     // sidebar / cell) AND a structured sentinel the model can recognize
     // on its next turn. Format: human summary on the first line,
@@ -3548,16 +3552,24 @@ async fn run_subagent_task(task: SubAgentTask) {
     }
 
     let payload = format!("{summary}\n{sentinel}");
+    let agent_id = task.agent_id.clone();
 
     // Wake the engine's parent turn loop if this is one of its direct
-    // children (issue #756). Gating by `spawn_depth == 1` means the parent
-    // only sees completions for agents it directly orchestrated, not for
-    // grandchildren spawned recursively inside its children.
-    emit_parent_completion(&task.runtime, &task.agent_id, &payload);
+    // children (issue #756). Issue #1961 also requires emit to happen
+    // before marking the manager terminal state so the parent can observe the
+    // completion while its "running children" gate is still open. If we
+    // update first, the parent can finalize before the completion arrives.
+    emit_parent_completion(&task.runtime, &agent_id, &payload);
+
+    let mut manager = task.manager_handle.write().await;
+    match &result {
+        Ok(res) => manager.update_from_result(&agent_id, res.clone()),
+        Err(err) => manager.update_failed(&agent_id, err.to_string()),
+    }
 
     if let Some(event_tx) = task.runtime.event_tx {
         let _ = event_tx.try_send(Event::AgentComplete {
-            id: task.agent_id,
+            id: agent_id.clone(),
             result: payload,
         });
     }
@@ -4976,7 +4988,9 @@ const SUBAGENT_OUTPUT_FORMAT: &str = include_str!("../../prompts/subagent_output
 const GENERAL_AGENT_INTRO: &str = concat!(
     "You are a general-purpose sub-agent spawned to handle a specific task autonomously.\n",
     "Stay inside the assigned scope; put adjacent work under RISKS/BLOCKERS.\n",
-    "Plan multi-step work with `checklist_write`; add `update_plan` for complex strategy.\n\n"
+    "Plan multi-step work with `checklist_write`; add `update_plan` for complex strategy.\n",
+    "**Stop quickly on failure**: if the same tool call fails 2 times in a row, stop retrying and return what you have so far with a one-line note explaining what's missing. Do not loop on impossible queries (e.g. external API unreachable, rate-limited, or returning empty).\n",
+    "**Bounded effort**: prefer one focused attempt over many speculative retries. If you cannot complete the task with available data within 3-5 tool calls, return your current partial findings — the parent agent can compensate with its own knowledge.\n\n"
 );
 
 const EXPLORE_AGENT_INTRO: &str = concat!(
diff --git a/crates/tui/src/tools/subagent/tests.rs b/crates/tui/src/tools/subagent/tests.rs
index 7f746412..39fd5780 100644
--- a/crates/tui/src/tools/subagent/tests.rs
+++ b/crates/tui/src/tools/subagent/tests.rs
@@ -2030,6 +2030,69 @@ fn emit_parent_completion_dropped_receiver_does_not_panic() {
     );
 }
 
+#[tokio::test]
+async fn run_subagent_task_emits_parent_completion_before_terminal_update() {
+    let manager = Arc::new(RwLock::new(SubAgentManager::new(PathBuf::from("."), 2)));
+    let (task_input_tx, task_input_rx) = mpsc::unbounded_channel();
+    let agent_id = "agent_noop".to_string();
+    let mut agent = SubAgent::new(
+        agent_id.clone(),
+        SubAgentType::General,
+        "noop".to_string(),
+        make_assignment(),
+        "deepseek-v4-flash".to_string(),
+        None,
+        None,
+        task_input_tx,
+        "boot_test".to_string(),
+    );
+    agent.status = SubAgentStatus::Running;
+    manager.write().await.agents.insert(agent_id.clone(), agent);
+
+    let (completion_tx, mut completion_rx) = mpsc::unbounded_channel::<SubAgentCompletion>();
+    let mut runtime = runtime_with_depth(1, Some(completion_tx));
+    runtime.manager = Arc::clone(&manager);
+
+    let task = SubAgentTask {
+        manager_handle: manager.clone(),
+        runtime,
+        agent_id: agent_id.clone(),
+        agent_type: SubAgentType::General,
+        prompt: "no-op child run".to_string(),
+        assignment: make_assignment(),
+        allowed_tools: None,
+        fork_context: false,
+        started_at: Instant::now(),
+        max_steps: 0,
+        input_rx: task_input_rx,
+    };
+
+    let manager_lock = manager.write().await;
+    let task_handle = tokio::spawn(run_subagent_task(task));
+
+    // While the manager write lock is held, completion can be emitted only if it
+    // is sent before the terminal-state manager update (the ordering fixed by
+    // issue #1961).
+    let completion = tokio::time::timeout(Duration::from_secs(1), completion_rx.recv())
+        .await
+        .expect("completion should be emitted while manager write lock is still held");
+    let completion = completion.expect("completion channel should remain open");
+    assert_eq!(completion.agent_id, agent_id);
+
+    drop(manager_lock);
+    task_handle
+        .await
+        .expect("run_subagent_task should complete after lock release");
+
+    let snapshot = {
+        let manager = manager.read().await;
+        manager
+            .get_result(&agent_id)
+            .expect("completed agent should be present")
+    };
+    assert_eq!(snapshot.status, SubAgentStatus::Completed);
+}
+
 #[test]
 fn child_runtime_propagates_completion_tx_for_gating() {
     // The channel is cloned through `child_runtime()` so descendants carry
diff --git a/crates/tui/src/tools/test_runner.rs b/crates/tui/src/tools/test_runner.rs
index ca96d014..6bbe42c4 100644
--- a/crates/tui/src/tools/test_runner.rs
+++ b/crates/tui/src/tools/test_runner.rs
@@ -10,6 +10,7 @@ use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
 
+use super::cargo_failure_summary::summarize_cargo_failure;
 use super::spec::{
     ApprovalRequirement, ToolCapability, ToolContext, ToolError, ToolResult, ToolSpec,
     optional_bool, optional_str,
@@ -100,7 +101,20 @@ impl ToolSpec for RunTestsTool {
             command: command_str,
         };
 
-        ToolResult::json(&result).map_err(|e| ToolError::execution_failed(e.to_string()))
+        let mut tool_result =
+            ToolResult::json(&result).map_err(|e| ToolError::execution_failed(e.to_string()))?;
+        if let Some(summary) = summarize_cargo_failure(
+            &result.command,
+            &result.stdout,
+            &result.stderr,
+            Some(result.exit_code),
+        ) {
+            tool_result = tool_result.with_metadata(json!({
+                "summary": summary.summary,
+                "cargo_failure_summary": summary.to_metadata_value(),
+            }));
+        }
+        Ok(tool_result)
     }
 }
 
@@ -255,6 +269,17 @@ mod tests {
             serde_json::from_str(&result.content).expect("tool result should be json");
         assert!(!parsed.success);
         assert_ne!(parsed.exit_code, 0);
+        let metadata = result.metadata.expect("metadata");
+        assert_eq!(
+            metadata["cargo_failure_summary"]["kind"],
+            json!("test_failure")
+        );
+        assert!(
+            metadata["cargo_failure_summary"]["summary"]
+                .as_str()
+                .unwrap()
+                .contains("Failing tests:")
+        );
     }
 
     #[test]
diff --git a/crates/tui/src/tools/truncate.rs b/crates/tui/src/tools/truncate.rs
index e0cadcae..4de0a540 100644
--- a/crates/tui/src/tools/truncate.rs
+++ b/crates/tui/src/tools/truncate.rs
@@ -81,6 +81,13 @@ pub fn spillover_root() -> Option<PathBuf> {
         return Some(root);
     }
 
+    // Prefer .codewhale, fall back to .deepseek
+    let primary = dirs::home_dir()?
+        .join(".codewhale")
+        .join(SPILLOVER_DIR_NAME);
+    if primary.exists() {
+        return Some(primary);
+    }
     Some(dirs::home_dir()?.join(".deepseek").join(SPILLOVER_DIR_NAME))
 }
 
diff --git a/crates/tui/src/tools/web_search.rs b/crates/tui/src/tools/web_search.rs
index d46cac7e..140ffc24 100644
--- a/crates/tui/src/tools/web_search.rs
+++ b/crates/tui/src/tools/web_search.rs
@@ -1,11 +1,12 @@
 //! Web search tool backed by multiple providers: Bing HTML scrape, DuckDuckGo
-//! (HTML scrape with Bing fallback), Tavily API, and Bocha (博查) API.
+//! (HTML scrape with Bing fallback), Tavily API, Bocha (博查) API,
+//! Metaso API (<https://metaso.cn>), and Baidu AI Search.
 //!
 //! This is the primary web search surface for agents. For browsing workflows
 //! (page open, click, screenshot) use a direct URL approach instead.
 //!
 //! Set `[search]` in config.toml to switch providers:
-//!   provider = "duckduckgo"  # or tavily/bocha
+//!   provider = "duckduckgo"  # or tavily/bocha/metaso/baidu
 //!   api_key = "tvly-..."
 
 use super::spec::{
@@ -25,6 +26,11 @@ const DUCKDUCKGO_HOST: &str = "html.duckduckgo.com";
 const BING_HOST: &str = "www.bing.com";
 const TAVILY_ENDPOINT: &str = "https://api.tavily.com/search";
 const BOCHA_ENDPOINT: &str = "https://api.bochaai.com/v1/ai/search";
+const METASO_ENDPOINT: &str = "https://metaso.cn/api/v1";
+const BAIDU_ENDPOINT: &str = "https://qianfan.baidubce.com/v2/ai_search/web_search";
+/// Intentionally public default key provided by Metaso for open-source/community use.
+/// Last-resort fallback after config and env var. Rate-limited to ~100 searches/day.
+const METASO_DEFAULT_API_KEY: &str = "mk-E384C1DD5E8501BB7EFE27C949AFDE5B";
 const ERROR_BODY_PREVIEW_BYTES: usize = 512;
 
 /// Returns `Ok(())` if the policy allows the call, or a `ToolError` otherwise.
@@ -52,6 +58,7 @@ static TAG_RE: OnceLock<Regex> = OnceLock::new();
 static BING_RESULT_RE: OnceLock<Regex> = OnceLock::new();
 static BING_TITLE_RE: OnceLock<Regex> = OnceLock::new();
 static BING_SNIPPET_RE: OnceLock<Regex> = OnceLock::new();
+static BEARER_TOKEN_RE: OnceLock<Regex> = OnceLock::new();
 
 fn get_title_re() -> &'static Regex {
     TITLE_RE.get_or_init(|| {
@@ -94,6 +101,13 @@ fn get_bing_snippet_re() -> &'static Regex {
     })
 }
 
+fn get_bearer_token_re() -> &'static Regex {
+    BEARER_TOKEN_RE.get_or_init(|| {
+        Regex::new(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+")
+            .expect("bearer token regex pattern is valid")
+    })
+}
+
 const DEFAULT_MAX_RESULTS: usize = 5;
 const MAX_RESULTS: usize = 10;
 const DEFAULT_TIMEOUT_MS: u64 = 15_000;
@@ -124,7 +138,7 @@ impl ToolSpec for WebSearchTool {
     }
 
     fn description(&self) -> &'static str {
-        "Search the web and return ranked results with URLs and snippets. Default backend is Bing; set `[search] provider = \"duckduckgo\" | \"tavily\" | \"bocha\"` in config.toml to switch backends. Use this instead of scraping search engines with `curl` in `exec_shell`. For a known canonical URL, prefer `fetch_url` directly."
+        "Search the web and return ranked results with URLs and snippets. Default backend is DuckDuckGo with Bing fallback; set `[search] provider = \"bing\" | \"tavily\" | \"bocha\" | \"metaso\" | \"baidu\"` in config.toml to switch backends. Use this instead of scraping search engines with `curl` in `exec_shell`. For a known canonical URL, prefer `fetch_url` directly."
     }
 
     fn input_schema(&self) -> Value {
@@ -198,6 +212,20 @@ impl ToolSpec for WebSearchTool {
                     .run_bocha_search(&query, max_results, timeout_ms, context)
                     .await;
             }
+            SearchProvider::Metaso => {
+                let decider = context.network_policy.as_ref();
+                check_policy(decider, "metaso.cn")?;
+                return self
+                    .run_metaso_search(&query, max_results, timeout_ms, context)
+                    .await;
+            }
+            SearchProvider::Baidu => {
+                let decider = context.network_policy.as_ref();
+                check_policy(decider, "qianfan.baidubce.com")?;
+                return self
+                    .run_baidu_search(&query, max_results, timeout_ms, context)
+                    .await;
+            }
             SearchProvider::Bing | SearchProvider::DuckDuckGo => {}
         }
 
@@ -210,10 +238,18 @@ impl ToolSpec for WebSearchTool {
                 ToolError::execution_failed(format!("Failed to build HTTP client: {e}"))
             })?;
 
+        // Track whether Bing was tried and returned zero, so we can surface
+        // the fallback in the result message (#2130).
+        let mut bing_was_empty = false;
+
         if matches!(context.search_provider, SearchProvider::Bing) {
             check_policy(decider, BING_HOST)?;
             let results = run_bing_search(&client, &query, max_results).await?;
-            return search_tool_result(query, "bing", results, None);
+            if !results.is_empty() {
+                return search_tool_result(query, "bing", results, None);
+            }
+            // Bing returned zero results — fall through to DuckDuckGo.
+            bing_was_empty = true;
         }
 
         // Per-domain network policy gate (#135). The "host" for web search is
@@ -250,7 +286,14 @@ impl ToolSpec for WebSearchTool {
 
         let mut results = parse_duckduckgo_results(&body, max_results);
         let mut source = "duckduckgo";
-        let mut message_suffix = None;
+        let mut message_suffix: Option<&str> = None;
+
+        // When Bing returned zero and we fell through to DuckDuckGo, surface
+        // the fallback in the result message (#2130).
+        if bing_was_empty && !results.is_empty() {
+            message_suffix = Some("Bing returned no results; used DuckDuckGo fallback");
+        }
+
         if results.is_empty() {
             let duckduckgo_blocked = is_duckduckgo_challenge(&body);
             // Bing is a separate host — gate it independently so a deny on
@@ -515,6 +558,176 @@ impl WebSearchTool {
 
         ToolResult::json(&response).map_err(|e| ToolError::execution_failed(e.to_string()))
     }
+
+    /// Search via Metaso AI Search API (<https://metaso.cn>). Falls back to
+    /// `METASO_API_KEY` env var then a built-in default key if no config key
+    /// is set.
+    async fn run_metaso_search(
+        &self,
+        query: &str,
+        max_results: usize,
+        timeout_ms: u64,
+        context: &ToolContext,
+    ) -> Result<ToolResult, ToolError> {
+        let env_key = std::env::var("METASO_API_KEY").ok();
+        let api_key = context
+            .search_api_key
+            .as_deref()
+            .or(env_key.as_deref())
+            .unwrap_or(METASO_DEFAULT_API_KEY);
+
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_millis(timeout_ms))
+            .build()
+            .map_err(|e| {
+                ToolError::execution_failed(format!("Failed to build HTTP client: {e}"))
+            })?;
+
+        let size = max_results.clamp(1, 100);
+        let payload = json!({
+            "q": query,
+            "scope": "webpage",
+            "size": size,
+        });
+
+        let resp = client
+            .post(format!("{METASO_ENDPOINT}/search"))
+            .header("Content-Type", "application/json")
+            .header("Authorization", format!("Bearer {api_key}"))
+            .json(&payload)
+            .send()
+            .await
+            .map_err(|e| {
+                ToolError::execution_failed(format!("Metaso search request failed: {e}"))
+            })?;
+
+        let status = resp.status();
+        let body = resp.text().await.map_err(|e| {
+            ToolError::execution_failed(format!("Failed to read Metaso response: {e}"))
+        })?;
+
+        if !status.is_success() {
+            let msg = match status.as_u16() {
+                401 | 403 => "Metaso API key rejected — check METASO_API_KEY or set `[search] api_key` in config.toml, or get one at https://metaso.cn/search-api/playground".to_string(),
+                429 => "Metaso rate-limited — wait and retry, or get your own API key at https://metaso.cn/search-api/playground".to_string(),
+                _ => {
+                    let truncated = truncate_error_body(&body);
+                    format!("Metaso server error (HTTP {status}) — {truncated}")
+                }
+            };
+            return Err(ToolError::execution_failed(msg));
+        }
+
+        let parsed: serde_json::Value = serde_json::from_str(&body).map_err(|e| {
+            ToolError::execution_failed(format!("Failed to parse Metaso response: {e}"))
+        })?;
+
+        // Check business-logic error codes in the response body.
+        if let Some(code) = parsed.get("code").and_then(|v| v.as_i64())
+            && code != 0
+        {
+            let msg = parsed
+                .get("message")
+                .and_then(|v| v.as_str())
+                .unwrap_or("unknown error");
+            return Err(ToolError::execution_failed(match code {
+                3003 => "Metaso: daily search limit reached — set METASO_API_KEY or get one at https://metaso.cn/search-api/playground".to_string(),
+                2005 => "Metaso API key rejected — check METASO_API_KEY or set `[search] api_key` in config.toml".to_string(),
+                _ => format!("Metaso API error (code {code}: {msg})"),
+            }));
+        }
+
+        let results: Vec<WebSearchEntry> = parsed
+            .get("webpages")
+            .and_then(|v| v.as_array())
+            .into_iter()
+            .flat_map(|arr| arr.iter())
+            .filter_map(|item| {
+                let title = item.get("title")?.as_str()?.to_string();
+                let url = item.get("link")?.as_str()?.to_string();
+                let snippet = item
+                    .get("snippet")
+                    .or_else(|| item.get("summary"))
+                    .and_then(|s| s.as_str())
+                    .map(|s| s.to_string());
+                Some(WebSearchEntry {
+                    title,
+                    url,
+                    snippet,
+                })
+            })
+            .take(size)
+            .collect();
+
+        search_tool_result(query.to_string(), "metaso", results, None)
+    }
+
+    /// Search via Baidu AI Search API (<https://qianfan.baidubce.com>).
+    async fn run_baidu_search(
+        &self,
+        query: &str,
+        max_results: usize,
+        timeout_ms: u64,
+        context: &ToolContext,
+    ) -> Result<ToolResult, ToolError> {
+        let env_key = std::env::var("BAIDU_SEARCH_API_KEY").ok();
+        let api_key = context
+            .search_api_key
+            .as_deref()
+            .or(env_key.as_deref())
+            .ok_or_else(|| {
+                ToolError::execution_failed(
+                    "Baidu search requires an API key. Set `BAIDU_SEARCH_API_KEY` or `[search] api_key` in config.toml.",
+                )
+            })?;
+
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_millis(timeout_ms))
+            .build()
+            .map_err(|e| {
+                ToolError::execution_failed(format!("Failed to build HTTP client: {e}"))
+            })?;
+
+        let payload = baidu_search_payload(query, max_results);
+
+        let resp = client
+            .post(BAIDU_ENDPOINT)
+            .header("Authorization", format!("Bearer {api_key}"))
+            .json(&payload)
+            .send()
+            .await
+            .map_err(|e| {
+                ToolError::execution_failed(format!("Baidu search request failed: {e}"))
+            })?;
+
+        let status = resp.status();
+        let body = resp.text().await.map_err(|e| {
+            ToolError::execution_failed(format!("Failed to read Baidu response: {e}"))
+        })?;
+
+        if !status.is_success() {
+            let msg = match status.as_u16() {
+                401 | 403 => "Baidu search API key rejected — check BAIDU_SEARCH_API_KEY or `[search] api_key` in config.toml".to_string(),
+                429 => "Baidu search rate-limited — wait and retry, or check your Baidu AI Search quota".to_string(),
+                _ => {
+                    let truncated = truncate_error_body(&body);
+                    format!("Baidu search failed: HTTP {} — {truncated}", status.as_u16())
+                }
+            };
+            return Err(ToolError::execution_failed(msg));
+        }
+
+        let parsed: serde_json::Value = serde_json::from_str(&body).map_err(|e| {
+            ToolError::execution_failed(format!("Failed to parse Baidu response: {e}"))
+        })?;
+
+        if let Some(error) = baidu_error_message(&parsed) {
+            return Err(ToolError::execution_failed(error));
+        }
+
+        let results = parse_baidu_results(&parsed, max_results);
+        search_tool_result(query.to_string(), "baidu", results, None)
+    }
 }
 
 fn truncate_error_body(body: &str) -> String {
@@ -532,12 +745,87 @@ fn truncate_error_body(body: &str) -> String {
 
 fn sanitize_error_body(body: &str) -> String {
     let stripped = strip_html_tags(body);
-    stripped
+    let visible: String = stripped
         .chars()
         .filter(|c| !c.is_control() || c.is_ascii_whitespace())
+        .collect();
+    get_bearer_token_re()
+        .replace_all(&visible, "Bearer [REDACTED]")
+        .to_string()
+}
+
+fn parse_baidu_results(parsed: &Value, max_results: usize) -> Vec<WebSearchEntry> {
+    parsed
+        .get("references")
+        .and_then(|v| v.as_array())
+        .into_iter()
+        .flat_map(|arr| arr.iter())
+        .filter_map(|item| {
+            let title = item
+                .get("title")
+                .or_else(|| item.get("name"))
+                .and_then(|s| s.as_str())?
+                .trim();
+            let url = item
+                .get("url")
+                .or_else(|| item.get("link"))
+                .and_then(|s| s.as_str())?
+                .trim();
+            if title.is_empty() || url.is_empty() {
+                return None;
+            }
+            let snippet = item
+                .get("content")
+                .or_else(|| item.get("snippet"))
+                .or_else(|| item.get("summary"))
+                .and_then(|s| s.as_str())
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+                .map(ToString::to_string);
+            Some(WebSearchEntry {
+                title: title.to_string(),
+                url: url.to_string(),
+                snippet,
+            })
+        })
+        .take(max_results)
         .collect()
 }
 
+fn baidu_error_message(parsed: &Value) -> Option<String> {
+    let code = parsed
+        .get("error_code")
+        .or_else(|| parsed.get("code"))
+        .and_then(|v| v.as_i64())?;
+    if code == 0 {
+        return None;
+    }
+    let message = parsed
+        .get("error_msg")
+        .or_else(|| parsed.get("message"))
+        .and_then(|v| v.as_str())
+        .unwrap_or("unknown error");
+    Some(format!("Baidu search API error (code {code}: {message})"))
+}
+
+fn baidu_search_payload(query: &str, max_results: usize) -> Value {
+    json!({
+        "messages": [
+            {
+                "role": "user",
+                "content": query,
+            }
+        ],
+        "search_source": "baidu_search_v2",
+        "resource_type_filter": [
+            {
+                "type": "web",
+                "top_k": max_results,
+            }
+        ],
+    })
+}
+
 fn extract_search_query(input: &Value) -> Result<String, ToolError> {
     for key in ["query", "q"] {
         if let Some(value) = input.get(key) {
@@ -771,6 +1059,14 @@ fn normalize_url(href: &str) -> String {
 }
 
 fn normalize_bing_url(href: &str) -> String {
+    // Bing wraps every SERP result URL in a `/ck/a?...&u=<base64>` click-tracking
+    // redirect, and in the raw HTML the separators are `&amp;` entities. Without
+    // decoding entities first, `extract_query_param` looks for `u` but the actual
+    // key is `amp;u`, so the real URL is never recovered: every result collapses to
+    // a `bing.com` root domain, which the spam heuristic then rejects — yielding
+    // zero results for the default Bing backend. Decode entities before parsing.
+    let href = decode_html_entities(href);
+    let href = href.as_str();
     if let Some(encoded) = extract_query_param(href, "u") {
         let decoded = percent_decode(&encoded);
         let token = decoded.strip_prefix("a1").unwrap_or(&decoded);
@@ -896,12 +1192,24 @@ fn extract_query_param(url: &str, key: &str) -> Option<String> {
 #[cfg(test)]
 mod tests {
     use super::{
-        ERROR_BODY_PREVIEW_BYTES, WebSearchEntry, WebSearchTool, decode_html_entities,
-        extract_search_query, is_likely_spam_results, optional_search_max_results, root_domain,
-        sanitize_error_body, truncate_error_body,
+        ERROR_BODY_PREVIEW_BYTES, WebSearchEntry, WebSearchTool, baidu_search_payload,
+        decode_html_entities, extract_search_query, is_likely_spam_results, normalize_bing_url,
+        optional_search_max_results, parse_baidu_results, root_domain, sanitize_error_body,
+        truncate_error_body,
     };
     use serde_json::json;
 
+    // Regression guard: Bing /ck/a redirect hrefs are HTML-entity-encoded
+    // (`&amp;`). normalize_bing_url must decode entities before extracting the
+    // `u=` base64 payload, otherwise the real URL is never recovered and the
+    // result's root domain collapses to bing.com (then dropped as spam → 0
+    // results for the default Bing backend).
+    #[test]
+    fn bing_ckurl_with_html_entities_decodes_real_url() {
+        let href = "https://www.bing.com/ck/a?!&amp;&amp;p=abc&amp;u=a1aHR0cHM6Ly9ydXN0LWxhbmcub3JnLw&amp;ntb=1";
+        assert_eq!(normalize_bing_url(href), "https://rust-lang.org/");
+    }
+
     fn entry(url: &str) -> WebSearchEntry {
         WebSearchEntry {
             title: "x".into(),
@@ -1165,6 +1473,96 @@ mod tests {
         assert_eq!(sanitized, "error");
     }
 
+    #[test]
+    fn sanitize_error_body_redacts_bearer_tokens() {
+        let body = r#"{"error":"bad token","authorization":"Bearer test-token/with+chars="}"#;
+
+        let sanitized = sanitize_error_body(body);
+
+        assert!(!sanitized.contains("test-token/with+chars="));
+        assert!(sanitized.contains("Bearer [REDACTED]"));
+    }
+
+    #[test]
+    fn parse_baidu_references_extracts_ranked_results() {
+        let body = json!({
+            "references": [
+                {
+                    "title": "Rust 官方文档",
+                    "url": "https://www.rust-lang.org/",
+                    "content": "Rust 是一门注重性能和可靠性的语言。"
+                },
+                {
+                    "title": "Cargo Book",
+                    "url": "https://doc.rust-lang.org/cargo/",
+                    "snippet": "Cargo is Rust's package manager."
+                }
+            ]
+        });
+
+        let results = parse_baidu_results(&body, 10);
+
+        assert_eq!(results.len(), 2);
+        assert_eq!(results[0].title, "Rust 官方文档");
+        assert_eq!(results[0].url, "https://www.rust-lang.org/");
+        assert_eq!(
+            results[0].snippet.as_deref(),
+            Some("Rust 是一门注重性能和可靠性的语言。")
+        );
+        assert_eq!(results[1].title, "Cargo Book");
+        assert_eq!(results[1].url, "https://doc.rust-lang.org/cargo/");
+        assert_eq!(
+            results[1].snippet.as_deref(),
+            Some("Cargo is Rust's package manager.")
+        );
+    }
+
+    #[test]
+    fn parse_baidu_references_skips_incomplete_entries() {
+        let body = json!({
+            "references": [
+                {"title": "No URL", "content": "missing url"},
+                {"url": "https://example.com/no-title", "content": "missing title"},
+                {"title": "Valid", "url": "https://example.com/valid"}
+            ]
+        });
+
+        let results = parse_baidu_results(&body, 10);
+
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].title, "Valid");
+        assert_eq!(results[0].url, "https://example.com/valid");
+        assert_eq!(results[0].snippet, None);
+    }
+
+    #[test]
+    fn baidu_search_payload_uses_official_search_source() {
+        let payload = baidu_search_payload("Rust cargo workspace", 3);
+
+        assert_eq!(
+            payload.get("search_source").and_then(|v| v.as_str()),
+            Some("baidu_search_v2")
+        );
+        assert_eq!(
+            payload
+                .get("messages")
+                .and_then(|v| v.as_array())
+                .and_then(|messages| messages.first())
+                .and_then(|message| message.get("content"))
+                .and_then(|v| v.as_str()),
+            Some("Rust cargo workspace")
+        );
+        assert_eq!(
+            payload
+                .get("resource_type_filter")
+                .and_then(|v| v.as_array())
+                .and_then(|filters| filters.first())
+                .and_then(|filter| filter.get("top_k"))
+                .and_then(|v| v.as_u64()),
+            Some(3)
+        );
+    }
+
     #[tokio::test]
     async fn tavily_provider_without_api_key_surfaces_clear_error_not_silent_fallback() {
         // Trust-boundary pin: if a user has opted into Tavily but
@@ -1210,4 +1608,59 @@ mod tests {
             "error must name the provider and missing key; got `{msg}`"
         );
     }
+
+    #[tokio::test]
+    async fn baidu_provider_without_api_key_surfaces_clear_error_not_silent_fallback() {
+        use crate::config::SearchProvider;
+        use crate::tools::spec::{ToolContext, ToolSpec};
+
+        let prev = std::env::var_os("BAIDU_SEARCH_API_KEY");
+        unsafe { std::env::remove_var("BAIDU_SEARCH_API_KEY") };
+
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let mut ctx = ToolContext::new(tmp.path().to_path_buf());
+        ctx.search_provider = SearchProvider::Baidu;
+        ctx.search_api_key = None;
+        let err = WebSearchTool
+            .execute(json!({"query": "anything"}), &ctx)
+            .await
+            .expect_err("missing api_key must surface as ToolError");
+
+        match prev {
+            Some(value) => unsafe { std::env::set_var("BAIDU_SEARCH_API_KEY", value) },
+            None => unsafe { std::env::remove_var("BAIDU_SEARCH_API_KEY") },
+        }
+
+        let msg = err.to_string();
+        assert!(
+            msg.contains("Baidu") && msg.contains("API key"),
+            "error must name the provider and missing key; got `{msg}`"
+        );
+    }
+
+    #[tokio::test]
+    async fn metaso_provider_uses_built_in_key_when_no_config_key_set() {
+        // Unlike Tavily/Bocha, Metaso falls back to a built-in default, so
+        // the call should NOT return an API-key-related error — it should
+        // either succeed or fail with a network-level error, but never a
+        // missing-key error.
+        use crate::config::SearchProvider;
+        use crate::tools::spec::{ToolContext, ToolSpec};
+
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let mut ctx = ToolContext::new(tmp.path().to_path_buf());
+        ctx.search_provider = SearchProvider::Metaso;
+        ctx.search_api_key = None;
+        let result = WebSearchTool
+            .execute(json!({"query": "anything"}), &ctx)
+            .await;
+        let msg = match &result {
+            Ok(res) => format!("{res:?}"),
+            Err(e) => e.to_string(),
+        };
+        assert!(
+            !msg.contains("API key"),
+            "should not complain about missing API key (built-in default); got `{msg}`"
+        );
+    }
 }
diff --git a/crates/tui/src/tui/app.rs b/crates/tui/src/tui/app.rs
index 4e5e78c0..990156b8 100644
--- a/crates/tui/src/tui/app.rs
+++ b/crates/tui/src/tui/app.rs
@@ -5,6 +5,7 @@ use std::path::{Path, PathBuf};
 use std::time::{Duration, Instant};
 
 use ratatui::layout::Rect;
+use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use thiserror::Error;
 
@@ -86,6 +87,9 @@ pub(crate) fn looks_like_slash_command_input(input: &str) -> bool {
     let Some(rest) = input.trim_start().strip_prefix('/') else {
         return false;
     };
+    if rest.chars().next().is_some_and(|ch| ch.is_whitespace()) {
+        return false;
+    }
     let Some(command) = rest.split_whitespace().next() else {
         return rest.is_empty();
     };
@@ -129,18 +133,6 @@ pub enum AppMode {
     Plan,
 }
 
-#[derive(Debug, Clone)]
-pub struct VoiceInputState {
-    pub started_at: Instant,
-}
-
-impl VoiceInputState {
-    #[must_use]
-    pub fn new(started_at: Instant) -> Self {
-        Self { started_at }
-    }
-}
-
 /// One row in the per-turn cache-telemetry ring (`/cache` debug surface, #263).
 #[derive(Debug, Clone)]
 pub struct TurnCacheRecord {
@@ -380,7 +372,7 @@ pub(crate) struct InputHistoryDraft {
     cursor: usize,
 }
 
-fn char_count(text: &str) -> usize {
+pub(crate) fn char_count(text: &str) -> usize {
     text.chars().count()
 }
 
@@ -823,7 +815,19 @@ pub struct TuiOptions {
     /// Used by `deepseek pr <N>` (#451) to drop the model into a
     /// session with the PR context already typed — the user can edit
     /// before sending or hit Enter to fire as-is.
-    pub initial_input: Option<String>,
+    pub initial_input: Option<InitialInput>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum InitialInput {
+    /// Pre-populate the composer and wait for the user to press Enter.
+    ///
+    /// Used by `codewhale pr <N>` (#451) to drop the model into a session
+    /// with the PR context already typed so the user can edit before sending.
+    Prefill(String),
+    /// Pre-populate the composer, submit it once startup is ready, then keep
+    /// the interactive session open for follow-up messages (#2370).
+    Submit(String),
 }
 
 #[derive(Debug, Clone, Copy)]
@@ -914,6 +918,10 @@ pub struct ComposerState {
     /// user presses `d` in Normal mode; cleared on the next key (either `d`
     /// to complete `dd`, or any other key to cancel).
     pub vim_pending_d: bool,
+    /// When set, the cursor is the active end of a text selection and
+    /// `selection_anchor` is the fixed end.  Both are char-indexed.
+    /// `None` means no selection is active.
+    pub selection_anchor: Option<usize>,
 }
 
 impl Default for ComposerState {
@@ -938,6 +946,7 @@ impl Default for ComposerState {
             vim_enabled: false,
             vim_mode: VimMode::Normal,
             vim_pending_d: false,
+            selection_anchor: None,
         }
     }
 }
@@ -952,11 +961,21 @@ pub struct ViewportState {
     pub selection_autoscroll: Option<SelectionAutoscroll>,
     pub transcript_scrollbar_dragging: bool,
     pub last_transcript_area: Option<Rect>,
+    pub last_composer_area: Option<Rect>,
     pub last_transcript_top: usize,
     pub last_transcript_visible: usize,
     pub last_transcript_total: usize,
     pub last_transcript_padding_top: usize,
     pub jump_to_latest_button_area: Option<Rect>,
+    /// Inner content rect of the composer (excluding border/padding),
+    /// stored at render time for mouse coordinate mapping.
+    pub last_composer_content: Option<Rect>,
+    /// Number of rendered text lines scrolled off the top of the composer,
+    /// stored at render time for mouse coordinate mapping.
+    pub last_composer_scroll_offset: usize,
+    /// Vertical padding above the first text line in the composer,
+    /// stored at render time for mouse coordinate mapping.
+    pub last_composer_top_padding: usize,
 }
 
 impl Default for ViewportState {
@@ -970,22 +989,42 @@ impl Default for ViewportState {
             selection_autoscroll: None,
             transcript_scrollbar_dragging: false,
             last_transcript_area: None,
+            last_composer_area: None,
             last_transcript_top: 0,
             last_transcript_visible: 0,
             last_transcript_total: 0,
             last_transcript_padding_top: 0,
             jump_to_latest_button_area: None,
+            last_composer_content: None,
+            last_composer_scroll_offset: 0,
+            last_composer_top_padding: 0,
         }
     }
 }
 
-/// Goal tracking state (#397).
+/// Verdict for a hunt (#2092).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum HuntVerdict {
+    Hunting,
+    Hunted,
+    Wounded,
+    Escaped,
+}
+
+impl Default for HuntVerdict {
+    fn default() -> Self {
+        Self::Hunting
+    }
+}
+
+/// Hunt tracking state (#2092 — was GoalState).
 #[derive(Debug, Clone, Default)]
-pub struct GoalState {
-    pub goal_objective: Option<String>,
-    pub goal_token_budget: Option<u32>,
-    pub goal_started_at: Option<Instant>,
-    pub goal_completed: bool,
+pub struct HuntState {
+    pub quarry: Option<String>,
+    pub token_budget: Option<u32>,
+    pub started_at: Option<Instant>,
+    pub verdict: HuntVerdict,
 }
 
 /// Session cost and token telemetry state.
@@ -1005,10 +1044,31 @@ pub struct SessionState {
     pub last_reasoning_replay_tokens: Option<u32>,
     pub total_tokens: u32,
     pub total_conversation_tokens: u32,
+    /// Accumulated token breakdown for the session.
+    pub total_input_tokens: u32,
+    pub total_cache_hit_tokens: u32,
+    pub total_cache_miss_tokens: u32,
+    pub total_output_tokens: u32,
     pub turn_cache_history: VecDeque<TurnCacheRecord>,
     pub last_cache_inspection: Option<PromptInspection>,
 }
 
+/// Sidebar hover state for mouse tooltip support.
+#[derive(Debug, Clone, Default)]
+pub struct SidebarHoverState {
+    /// Rendered sections with their areas and full-text lines.
+    pub sections: Vec<SidebarHoverSection>,
+}
+
+/// Per-section metadata for sidebar hover detection.
+#[derive(Debug, Clone)]
+pub struct SidebarHoverSection {
+    /// Content area within the section (inside border + padding).
+    pub content_area: Rect,
+    /// Full original text for each content line rendered.
+    pub lines: Vec<String>,
+}
+
 impl Default for SessionState {
     fn default() -> Self {
         Self {
@@ -1026,12 +1086,26 @@ impl Default for SessionState {
             last_reasoning_replay_tokens: None,
             total_tokens: 0,
             total_conversation_tokens: 0,
+            total_input_tokens: 0,
+            total_cache_hit_tokens: 0,
+            total_cache_miss_tokens: 0,
+            total_output_tokens: 0,
             turn_cache_history: VecDeque::new(),
             last_cache_inspection: None,
         }
     }
 }
 
+impl SessionState {
+    /// Reset the accumulated token breakdown fields to zero.
+    pub fn reset_token_breakdown(&mut self) {
+        self.total_input_tokens = 0;
+        self.total_cache_hit_tokens = 0;
+        self.total_cache_miss_tokens = 0;
+        self.total_output_tokens = 0;
+    }
+}
+
 /// Evidence collected during a turn for the post-turn receipt.
 #[derive(Debug, Clone)]
 pub struct ToolEvidence {
@@ -1048,9 +1122,12 @@ pub struct App {
     /// Viewport sub-state (scroll, cache, selection).
     pub viewport: ViewportState,
     /// Goal sub-state.
-    pub goal: GoalState,
+    pub hunt: HuntState,
     /// Session sub-state (cost, tokens, telemetry).
     pub session: SessionState,
+    /// Active tool restriction from custom slash command frontmatter.
+    /// `None` means the current turn may use the normal tool set.
+    pub active_allowed_tools: Option<Vec<String>>,
     pub history: Vec<HistoryCell>,
     pub history_version: u64,
     /// Per-cell revision counter, kept in lockstep with `history`.
@@ -1074,8 +1151,6 @@ pub struct App {
     pub sticky_status: Option<StatusToast>,
     /// Last status text already promoted from `status_message` into toast state.
     pub last_status_message_seen: Option<String>,
-    /// Active external speech-to-text helper launched from the command palette.
-    pub voice_input_state: Option<VoiceInputState>,
     pub model: String,
     /// When true, the model is auto-selected based on request complexity
     /// rather than using a fixed model. The `/model auto` command sets this.
@@ -1156,6 +1231,12 @@ pub struct App {
     pub transcript_spacing: TranscriptSpacing,
     pub sidebar_width_percent: u16,
     pub sidebar_focus: SidebarFocus,
+    /// Sidebar hover state for mouse tooltip support.
+    pub sidebar_hover: SidebarHoverState,
+    /// Current hover tooltip text, if any.
+    pub sidebar_hover_tooltip: Option<String>,
+    /// Last known mouse position for tooltip placement.
+    pub last_mouse_pos: Option<(u16, u16)>,
     /// Whether the session-context panel is enabled (#504).
     pub context_panel: bool,
     /// File-tree pane state. `None` when hidden; `Some` when visible.
@@ -1380,6 +1461,8 @@ pub struct App {
     pub thinking_started_at: Option<Instant>,
     /// Whether context compaction is currently in progress.
     pub is_compacting: bool,
+    /// Whether context purge is currently in progress.
+    pub is_purging: bool,
     /// Set when the user scrolls up/down during a streaming turn so subsequent
     /// streamed chunks don't yank the view back to the live tail. Cleared
     /// when the user explicitly returns to bottom or the turn completes.
@@ -1391,6 +1474,8 @@ pub struct App {
     /// Most recent user prompt accepted for an active engine turn. Ctrl+C can
     /// restore this into an empty composer after cancelling that turn.
     pub last_submitted_prompt: Option<String>,
+    /// Startup prompt should be submitted automatically after the engine is ready.
+    pub auto_submit_initial_input: bool,
     /// Two-tap quit confirmation. When set, a prior Ctrl+C in idle state has
     /// armed the quit shortcut; a second Ctrl+C before this `Instant` exits
     /// the app, while expiry silently re-arms the prompt for next time.
@@ -1416,6 +1501,10 @@ pub struct App {
     pub prefix_stability_pct: Option<u32>,
     /// Description of the last prefix change, if any.
     pub last_prefix_change_desc: Option<String>,
+    /// Current pinned prefix combined hash (SHA-256, 64 hex chars).
+    /// Updated per-turn via PrefixCacheChange events; surfaced by
+    /// `/cache stats` for cache-hit debugging.
+    pub last_pinned_prefix_hash: Option<String>,
 
     /// Active cycle configuration (token threshold, briefing cap, per-model
     /// overrides). Loaded from config and forwarded to the engine.
@@ -1425,6 +1514,10 @@ pub struct App {
     /// Transcript cells the user has collapsed (hidden from view).
     /// Stores **original** virtual cell indices (pre-filtering).
     pub collapsed_cells: HashSet<usize>,
+    /// Thinking cells the user has folded (showing summary instead of full
+    /// content). Stores **original** virtual cell indices. Toggled by Space
+    /// when the composer is empty and the cursor is on a thinking cell.
+    pub folded_thinking: HashSet<usize>,
     /// Mapping from filtered cell index → original virtual index.
     /// Populated during `ChatWidget::new` by filtering out collapsed cells.
     /// Used by `build_context_menu_entries` to convert line-meta indices
@@ -1549,8 +1642,8 @@ fn default_composer_arrows_scroll(use_mouse_capture: bool) -> bool {
     default_composer_arrows_scroll_for_platform(use_mouse_capture, cfg!(windows))
 }
 
-fn default_composer_arrows_scroll_for_platform(use_mouse_capture: bool, is_windows: bool) -> bool {
-    is_windows || !use_mouse_capture
+fn default_composer_arrows_scroll_for_platform(use_mouse_capture: bool, _is_windows: bool) -> bool {
+    !use_mouse_capture
 }
 
 impl App {
@@ -1574,6 +1667,7 @@ impl App {
         self.session.last_prompt_cache_miss_tokens = None;
         self.session.last_reasoning_replay_tokens = None;
         self.session.turn_cache_history.clear();
+        self.last_pinned_prefix_hash = None;
     }
 
     pub fn tr(&self, id: MessageId) -> &'static str {
@@ -1745,17 +1839,22 @@ impl App {
         let cached_skills = Self::discover_cached_skills(&workspace, &skills_dir);
 
         let input_history = crate::composer_history::load_history();
-        let (initial_input_text, initial_input_cursor) = match initial_input {
-            // #451: pre-populate the composer when invoked via
-            // `deepseek pr <N>` (or any future caller that wants to
-            // drop the model into a session with context already
-            // typed). Cursor lands at the end so Enter sends as-is.
-            Some(text) if !text.is_empty() => {
-                let cursor = text.len();
-                (text, cursor)
-            }
-            _ => (String::new(), 0),
-        };
+        let (initial_input_text, initial_input_cursor, auto_submit_initial_input) =
+            match initial_input {
+                // #451: pre-populate the composer when invoked via
+                // `deepseek pr <N>` (or any future caller that wants to
+                // drop the model into a session with context already
+                // typed). Cursor lands at the end so Enter sends as-is.
+                Some(InitialInput::Prefill(text)) if !text.is_empty() => {
+                    let cursor = text.chars().count();
+                    (text, cursor, false)
+                }
+                Some(InitialInput::Submit(text)) if !text.is_empty() => {
+                    let cursor = text.chars().count();
+                    (text, cursor, true)
+                }
+                _ => (String::new(), 0, false),
+            };
         Self {
             mode: initial_mode,
             composer: ComposerState {
@@ -1778,10 +1877,12 @@ impl App {
                 vim_enabled: composer_vim_enabled,
                 vim_mode: VimMode::Normal,
                 vim_pending_d: false,
+                selection_anchor: None,
             },
             viewport: ViewportState::default(),
-            goal: GoalState::default(),
+            hunt: HuntState::default(),
             session: SessionState::default(),
+            active_allowed_tools: None,
             history: Vec::new(),
             history_version: 0,
             history_revisions: Vec::new(),
@@ -1794,7 +1895,6 @@ impl App {
             status_toasts: VecDeque::new(),
             sticky_status: None,
             last_status_message_seen: None,
-            voice_input_state: None,
             model,
             auto_model,
             last_effective_model: None,
@@ -1830,6 +1930,9 @@ impl App {
             transcript_spacing,
             sidebar_width_percent,
             sidebar_focus,
+            sidebar_hover: SidebarHoverState::default(),
+            sidebar_hover_tooltip: None,
+            last_mouse_pos: None,
             context_panel: settings.context_panel,
             file_tree: None,
             file_tree_visible: false,
@@ -1938,10 +2041,12 @@ impl App {
             needs_redraw: true,
             thinking_started_at: None,
             is_compacting: false,
+            is_purging: false,
             user_scrolled_during_stream: false,
             coherence_state: CoherenceState::default(),
             last_send_at: None,
             last_submitted_prompt: None,
+            auto_submit_initial_input,
             quit_armed_until: None,
             cycle_count: 0,
             cycle_briefings: Vec::new(),
@@ -1949,8 +2054,10 @@ impl App {
             prefix_checks_total: 0,
             prefix_stability_pct: None,
             last_prefix_change_desc: None,
+            last_pinned_prefix_hash: None,
             cycle: CycleConfig::default(),
             collapsed_cells: HashSet::new(),
+            folded_thinking: HashSet::new(),
             collapsed_cell_map: Vec::new(),
             edit_in_progress: false,
             lsp_enabled: config.lsp.as_ref().and_then(|l| l.enabled).unwrap_or(true),
@@ -2195,6 +2302,9 @@ impl App {
         metadata.cost.subagent_cost_cny = self.session.subagent_cost_cny;
         metadata.cost.displayed_cost_high_water_usd = self.session.displayed_cost_high_water;
         metadata.cost.displayed_cost_high_water_cny = self.session.displayed_cost_high_water_cny;
+        // Persist cumulative turn duration so the footer "worked" chip
+        // survives session save/restore (#2038).
+        metadata.cumulative_turn_secs = self.cumulative_turn_duration.as_secs();
     }
 
     /// Recompute the displayed cost high-water mark. Called any time a cost
@@ -2254,6 +2364,18 @@ impl App {
         crate::pricing::format_cost_amount_precise(amount, self.cost_currency)
     }
 
+    /// Estimated cost saved by the last turn's cache-hit tokens in the
+    /// configured display currency.  Returns `None` when the model's pricing
+    /// is unknown or there were no cache hits.
+    pub fn last_turn_cache_savings(&self) -> Option<f64> {
+        let hit_tokens = self.session.last_prompt_cache_hit_tokens?;
+        let estimate = crate::pricing::calculate_cache_savings(&self.model, hit_tokens)?;
+        Some(match self.cost_currency {
+            crate::pricing::CostCurrency::Usd => estimate.usd,
+            crate::pricing::CostCurrency::Cny => estimate.cny,
+        })
+    }
+
     /// Fold the oldest [`Self::HISTORY_FOLD_BATCH`] cells into a single
     /// `ArchivedContext` placeholder when history exceeds the soft cap.
     /// Called from [`Self::add_message`]; the caller is responsible for
@@ -3075,6 +3197,7 @@ impl App {
         if text.is_empty() {
             return;
         }
+        self.delete_selection();
         self.selected_attachment_index = None;
         let cursor = self.cursor_position.min(char_count(&self.input));
         let byte_index = byte_index_at_char(&self.input, cursor);
@@ -3096,14 +3219,11 @@ impl App {
             self.insert_str(&normalized);
         }
         self.paste_burst.clear_after_explicit_paste();
-        // Visible-before-submit consolidation: when the post-paste input
-        // is over the cap, swap it for an @paste-…md mention immediately
-        // (instead of waiting until the user presses Enter and getting
-        // surprised by an auto-sent @mention). The same logic runs as a
-        // safety-net at submit time so any other code path that fills
-        // self.input above the cap still consolidates rather than
-        // silently truncating.
-        self.consolidate_large_input_if_oversized();
+        // Large pasted input stays editable and visible until submit. The
+        // submit-time safety net consolidates oversized composer content into
+        // an @paste-...md mention before dispatch, so no path silently
+        // truncates user input.
+        // self.consolidate_large_input_if_oversized(); // deferred to submit time
     }
 
     pub fn insert_media_attachment(&mut self, kind: &str, path: &Path, description: Option<&str>) {
@@ -3337,6 +3457,7 @@ impl App {
 
     pub fn insert_char(&mut self, c: char) {
         self.clear_input_history_navigation();
+        self.delete_selection();
         self.selected_attachment_index = None;
         let cursor = self.cursor_position.min(char_count(&self.input));
         let byte_index = byte_index_at_char(&self.input, cursor);
@@ -3363,6 +3484,9 @@ impl App {
 
     pub fn delete_char(&mut self) {
         self.clear_input_history_navigation();
+        if self.delete_selection() {
+            return;
+        }
         self.selected_attachment_index = None;
         if self.cursor_position == 0 {
             return;
@@ -3380,6 +3504,9 @@ impl App {
 
     pub fn delete_char_forward(&mut self) {
         self.clear_input_history_navigation();
+        if self.delete_selection() {
+            return;
+        }
         self.selected_attachment_index = None;
         if self.input.is_empty() {
             return;
@@ -3398,6 +3525,9 @@ impl App {
     /// Delete the word before the cursor.
     pub fn delete_word_backward(&mut self) {
         self.clear_input_history_navigation();
+        if self.delete_selection() {
+            return;
+        }
         self.selected_attachment_index = None;
         if self.cursor_position == 0 {
             return;
@@ -3439,6 +3569,9 @@ impl App {
     /// Delete from the cursor to the start of the line.
     pub fn delete_to_start_of_line(&mut self) {
         self.clear_input_history_navigation();
+        if self.delete_selection() {
+            return;
+        }
         self.selected_attachment_index = None;
         if self.cursor_position == 0 {
             return;
@@ -3464,6 +3597,9 @@ impl App {
     /// Delete the word after the cursor.
     pub fn delete_word_forward(&mut self) {
         self.clear_input_history_navigation();
+        if self.delete_selection() {
+            return;
+        }
         self.selected_attachment_index = None;
         let cursor_byte = byte_index_at_char(&self.input, self.cursor_position);
         if cursor_byte >= self.input.len() {
@@ -3508,6 +3644,13 @@ impl App {
     /// Returns `true` when bytes were moved into the kill buffer.
     pub fn kill_to_end_of_line(&mut self) -> bool {
         self.clear_input_history_navigation();
+        if let Some((start, end)) = self.selection_range() {
+            let sb = byte_index_at_char(&self.input, start);
+            let eb = byte_index_at_char(&self.input, end);
+            self.kill_buffer = self.input[sb..eb].to_string();
+            self.delete_selection();
+            return true;
+        }
         let total_chars = char_count(&self.input);
         let cursor = self.cursor_position.min(total_chars);
         let start_byte = byte_index_at_char(&self.input, cursor);
@@ -3553,6 +3696,7 @@ impl App {
         if self.kill_buffer.is_empty() {
             return false;
         }
+        self.delete_selection();
         self.clear_input_history_navigation();
         let text = self.kill_buffer.clone();
         let cursor = self.cursor_position.min(char_count(&self.input));
@@ -3678,6 +3822,59 @@ impl App {
         self.needs_redraw = true;
     }
 
+    // === Selection helpers ===
+
+    /// Return the (start, end) of the active selection, or `None`.
+    /// `start` is inclusive, `end` is exclusive; both are char indices.
+    pub fn selection_range(&self) -> Option<(usize, usize)> {
+        let total = char_count(&self.input);
+        let anchor = self.selection_anchor?.min(total);
+        let cursor = self.cursor_position.min(total);
+        if anchor == cursor {
+            return None;
+        }
+        Some(if anchor < cursor {
+            (anchor, cursor)
+        } else {
+            (cursor, anchor)
+        })
+    }
+
+    /// Return the selected text, or empty string if no selection.
+    pub fn selected_text(&self) -> String {
+        self.selection_range()
+            .map(|(s, e)| {
+                let sb = byte_index_at_char(&self.input, s);
+                let eb = byte_index_at_char(&self.input, e);
+                self.input[sb..eb].to_string()
+            })
+            .unwrap_or_default()
+    }
+
+    /// Delete the selected text, place cursor at the start of the deleted range.
+    /// Returns true if a selection was deleted.
+    pub fn delete_selection(&mut self) -> bool {
+        let Some((start, end)) = self.selection_range() else {
+            return false;
+        };
+        let sb = byte_index_at_char(&self.input, start);
+        let eb = byte_index_at_char(&self.input, end);
+        self.input.replace_range(sb..eb, "");
+        self.cursor_position = start;
+        self.selection_anchor = None;
+        self.clear_input_history_navigation();
+        self.slash_menu_hidden = false;
+        self.mention_menu_hidden = false;
+        self.mention_menu_selected = 0;
+        self.needs_redraw = true;
+        true
+    }
+
+    /// Clear the selection without moving the cursor.
+    pub fn clear_selection(&mut self) {
+        self.selection_anchor = None;
+    }
+
     // === Vim composer mode helpers ===
 
     /// Move the cursor to the start of the current logical line (vim `0`).
@@ -3860,6 +4057,7 @@ impl App {
         self.clear_input_history_navigation();
         self.input.clear();
         self.cursor_position = 0;
+        self.selection_anchor = None;
         self.selected_attachment_index = None;
         self.slash_menu_selected = 0;
         self.slash_menu_hidden = false;
@@ -4230,7 +4428,7 @@ impl App {
         self.input = format!("@{rel_path}");
         self.cursor_position = char_count(&self.input);
         self.push_status_toast(
-            "Large paste consolidated — sent as @mention",
+            "Large paste consolidated — auto-wrote to file and replaced with @mention. The text is still fully accessible to the model.",
             StatusToastLevel::Info,
             Some(5_000),
         );
@@ -4366,6 +4564,7 @@ impl App {
         self.history_index = Some(new_index);
         self.input = self.input_history[new_index].clone();
         self.cursor_position = char_count(&self.input);
+        self.selection_anchor = None;
         self.selected_attachment_index = None;
         self.slash_menu_hidden = false;
         self.paste_burst.clear_after_explicit_paste();
@@ -4382,6 +4581,7 @@ impl App {
                     self.history_index = Some(i + 1);
                     self.input = self.input_history[i + 1].clone();
                     self.cursor_position = char_count(&self.input);
+                    self.selection_anchor = None;
                     self.selected_attachment_index = None;
                     self.slash_menu_hidden = false;
                     self.paste_burst.clear_after_explicit_paste();
@@ -4390,6 +4590,7 @@ impl App {
                     if let Some(draft) = self.history_navigation_draft.take() {
                         self.input = draft.input;
                         self.cursor_position = draft.cursor.min(char_count(&self.input));
+                        self.selection_anchor = None;
                         self.selected_attachment_index = None;
                         self.slash_menu_hidden = false;
                         self.paste_burst.clear_after_explicit_paste();
@@ -4455,6 +4656,10 @@ impl App {
         };
         self.auto_model = auto_model;
         self.last_effective_model = None;
+        self.last_effective_reasoning_effort = None;
+        if auto_model {
+            self.reasoning_effort = ReasoningEffort::Auto;
+        }
     }
 
     pub fn model_selection_for_persistence(&self) -> String {
@@ -4580,6 +4785,7 @@ pub enum AppAction {
     UpdateCompaction(CompactionConfig),
     OpenContextInspector,
     CompactContext,
+    PurgeContext,
     TaskAdd {
         prompt: String,
     },
@@ -4644,6 +4850,7 @@ pub enum McpUiAction {
     AddHttp {
         name: String,
         url: String,
+        transport: Option<String>,
     },
     Enable {
         name: String,
@@ -4694,6 +4901,35 @@ mod tests {
         }
     }
 
+    #[test]
+    fn initial_input_prefill_waits_for_manual_submit() {
+        let mut options = test_options(false);
+        options.initial_input = Some(InitialInput::Prefill("review this PR".to_string()));
+
+        let app = App::new(options, &Config::default());
+
+        assert_eq!(app.input, "review this PR");
+        assert_eq!(app.cursor_position, "review this PR".chars().count());
+        assert!(!app.auto_submit_initial_input);
+    }
+
+    #[test]
+    fn initial_input_submit_marks_startup_dispatch() {
+        let mut options = test_options(false);
+        options.initial_input = Some(InitialInput::Submit(
+            "阅读项目 and wait for instructions".to_string(),
+        ));
+
+        let app = App::new(options, &Config::default());
+
+        assert_eq!(app.input, "阅读项目 and wait for instructions");
+        assert_eq!(
+            app.cursor_position,
+            "阅读项目 and wait for instructions".chars().count()
+        );
+        assert!(app.auto_submit_initial_input);
+    }
+
     #[test]
     fn composer_arrows_scroll_default_is_true_without_mouse_capture() {
         assert!(default_composer_arrows_scroll_for_platform(false, false));
@@ -4705,8 +4941,13 @@ mod tests {
     }
 
     #[test]
-    fn composer_arrows_scroll_default_is_true_on_windows_even_with_mouse_capture() {
-        assert!(default_composer_arrows_scroll_for_platform(true, true));
+    fn composer_arrows_scroll_default_is_false_with_mouse_capture_on_windows() {
+        assert!(!default_composer_arrows_scroll_for_platform(true, true));
+    }
+
+    #[test]
+    fn composer_arrows_scroll_default_is_true_without_mouse_capture_on_windows() {
+        assert!(default_composer_arrows_scroll_for_platform(false, true));
     }
 
     #[test]
@@ -4853,6 +5094,8 @@ mod tests {
         assert!(looks_like_slash_command_input("/"));
         assert!(looks_like_slash_command_input("/help"));
         assert!(looks_like_slash_command_input("/model deepseek-v4-pro"));
+        assert!(!looks_like_slash_command_input("/ hello"));
+        assert!(!looks_like_slash_command_input("  / hello"));
         assert!(!looks_like_slash_command_input(
             "/usr/lib/x86_64-linux-gnu/ 是标准路径吗？"
         ));
@@ -5270,12 +5513,10 @@ mod tests {
     }
 
     #[test]
-    fn paste_consolidates_oversized_text_into_paste_file_visibly() {
-        // Visible-before-submit consolidation (paste UX): when a single
-        // bracketed paste exceeds the safety cap, the @mention must
-        // replace the input *immediately*, so the user sees what's
-        // about to be sent before pressing Enter — not as a side effect
-        // of submit.
+    fn paste_defers_oversized_text_consolidation_until_submit() {
+        // #2168: a large paste stays inline so the user can still edit it.
+        // Submit-time consolidation then writes the paste file and sends the
+        // @mention instead of the raw oversized content.
         let tmp = tempfile::TempDir::new().expect("tempdir");
         let mut opts = test_options(false);
         opts.workspace = tmp.path().to_path_buf();
@@ -5284,26 +5525,35 @@ mod tests {
 
         app.insert_paste_text(&full_content);
 
-        // Composer should now contain the @mention, not the full text.
-        assert!(
-            app.input.starts_with("@.deepseek/pastes/paste-") && app.input.ends_with(".md"),
-            "expected @mention in composer after large paste, got: {}",
-            app.input
-        );
-        // The cursor moves to the end of the @mention.
+        assert_eq!(app.input, full_content);
         assert_eq!(app.cursor_position, app.input.chars().count());
-        // The paste file must exist with the full content.
-        let rel_path = &app.input[1..];
+        let pastes_dir = tmp.path().join(".deepseek/pastes");
+        assert!(
+            !pastes_dir.exists() || std::fs::read_dir(&pastes_dir).unwrap().next().is_none(),
+            "paste file should not be written before submit"
+        );
+        assert!(
+            app.status_toasts
+                .iter()
+                .all(|toast| !toast.text.contains("consolidated")),
+            "consolidation toast should not appear before submit"
+        );
+
+        let submitted = app.submit_input().expect("expected submitted input");
+        assert!(
+            submitted.starts_with("@.deepseek/pastes/paste-") && submitted.ends_with(".md"),
+            "expected @mention after submit, got: {submitted}"
+        );
+        let rel_path = &submitted[1..];
         let abs = tmp.path().join(rel_path);
         assert!(abs.is_file(), "paste file must exist at {abs:?}");
         let written = std::fs::read_to_string(&abs).expect("read");
         assert_eq!(written, full_content);
-        // A toast confirms what happened so the user isn't surprised.
         assert!(
             app.status_toasts
                 .iter()
-                .any(|t| t.text.contains("consolidated")),
-            "expected consolidation toast"
+                .any(|toast| toast.text.contains("consolidated")),
+            "expected consolidation toast after submit"
         );
     }
 
@@ -5758,6 +6008,22 @@ mod tests {
         assert!(app.history_index.is_none());
     }
 
+    #[test]
+    fn input_history_navigation_clears_stale_selection() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input_history.push("previous input".to_string());
+        app.input = "hello world".to_string();
+        app.cursor_position = "hello ".chars().count();
+        app.selection_anchor = Some(app.input.chars().count());
+
+        app.history_up();
+        assert_eq!(app.input, "previous input");
+        assert!(app.selection_anchor.is_none());
+
+        app.insert_char('x');
+        assert_eq!(app.input, "previous inputx");
+    }
+
     #[test]
     fn input_history_restores_empty_draft_at_end_of_navigation() {
         let mut app = App::new(test_options(false), &Config::default());
@@ -6604,4 +6870,107 @@ mod tests {
         assert_eq!(app.input, "café 你好");
         assert_eq!(app.cursor_position, 7);
     }
+
+    #[test]
+    fn selection_range_returns_none_when_no_anchor() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 5;
+        app.selection_anchor = None;
+        assert!(app.selection_range().is_none());
+    }
+
+    #[test]
+    fn selection_range_returns_ordered_range() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 5;
+        app.selection_anchor = Some(2);
+        assert_eq!(app.selection_range(), Some((2, 5)));
+    }
+
+    #[test]
+    fn selection_range_normalizes_order() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 2;
+        app.selection_anchor = Some(5);
+        assert_eq!(app.selection_range(), Some((2, 5)));
+    }
+
+    #[test]
+    fn selection_range_returns_none_when_anchor_equals_cursor() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello".to_string();
+        app.cursor_position = 3;
+        app.selection_anchor = Some(3);
+        assert!(app.selection_range().is_none());
+    }
+
+    #[test]
+    fn delete_selection_removes_selected_text() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 5;
+        app.selection_anchor = Some(2);
+        assert!(app.delete_selection());
+        assert_eq!(app.input, "he world");
+        assert_eq!(app.cursor_position, 2);
+        assert!(app.selection_anchor.is_none());
+    }
+
+    #[test]
+    fn insert_char_replaces_selection() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 5;
+        app.selection_anchor = Some(2);
+        app.insert_char('X');
+        assert_eq!(app.input, "heX world");
+        assert_eq!(app.cursor_position, 3);
+        assert!(app.selection_anchor.is_none());
+    }
+
+    #[test]
+    fn delete_char_removes_selection_instead_of_single_char() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 5;
+        app.selection_anchor = Some(2);
+        app.delete_char();
+        assert_eq!(app.input, "he world");
+        assert_eq!(app.cursor_position, 2);
+    }
+
+    #[test]
+    fn selected_text_returns_correct_substring() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 5;
+        app.selection_anchor = Some(2);
+        assert_eq!(app.selected_text(), "llo");
+    }
+
+    #[test]
+    fn insert_str_replaces_selection() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello world".to_string();
+        app.cursor_position = 5;
+        app.selection_anchor = Some(2);
+        app.insert_str("yo");
+        assert_eq!(app.input, "heyo world");
+        assert_eq!(app.cursor_position, 4);
+        assert!(app.selection_anchor.is_none());
+    }
+
+    #[test]
+    fn delete_selection_noop_when_no_selection() {
+        let mut app = App::new(test_options(false), &Config::default());
+        app.input = "hello".to_string();
+        app.cursor_position = 3;
+        app.selection_anchor = None;
+        assert!(!app.delete_selection());
+        assert_eq!(app.input, "hello");
+        assert_eq!(app.cursor_position, 3);
+    }
 }
diff --git a/crates/tui/src/tui/approval.rs b/crates/tui/src/tui/approval.rs
index dc7e9cdc..92e3208e 100644
--- a/crates/tui/src/tui/approval.rs
+++ b/crates/tui/src/tui/approval.rs
@@ -16,10 +16,9 @@
 //!   `2` / `a` approves for the session.
 //! - **Destructive** (`RiskLevel::Destructive`) — file writes, shell,
 //!   patches, MCP actions, unclassified tools, and any "fetch arbitrary
-//!   content" surface. The first approve press *stages* a decision and
-//!   the second matching press commits — muscle-memory `Enter` cannot
-//!   accidentally land on an approval. Any non-approve key clears the
-//!   staging and keeps the user in selection mode.
+//!   content" surface. The takeover keeps the destructive badge and
+//!   impact summary visible, then lets `Enter` commit the highlighted
+//!   option or `y` / `a` / `d` commit directly.
 //!
 //! The decision events emitted upstream are unchanged
 //! (`ViewEvent::ApprovalDecision`), so `ui.rs` and the engine handle
@@ -102,8 +101,8 @@ pub enum ToolCategory {
 /// Stakes-based variant for the takeover modal.
 ///
 /// `RiskLevel::Benign` lets a single keystroke commit the approval.
-/// `RiskLevel::Destructive` requires an explicit second confirmation
-/// keypress so muscle-memory `Enter` never lands on an irreversible op.
+/// `RiskLevel::Destructive` keeps stronger warning copy and styling
+/// around approvals that can touch files, shell, or remote state.
 ///
 /// Routing rules live in [`classify_risk`] — when in doubt, route to
 /// `Destructive`.
@@ -228,13 +227,12 @@ pub fn get_tool_category(name: &str) -> ToolCategory {
 /// The bias is conservative: a category we don't recognise routes to
 /// `Destructive`, and any shell command that `command_safety` flags as
 /// `Dangerous` is forced to `Destructive` even when the rest of the
-/// request looks calm. The split lets the modal swap muscle-memory
-/// approval for an explicit two-key confirmation on anything that can
-/// touch state outside this turn.
+/// request looks calm. The split lets the modal render stronger warning
+/// copy on anything that can touch state outside this turn.
 #[must_use]
 pub fn classify_risk(tool_name: &str, category: ToolCategory, params: &Value) -> RiskLevel {
     match category {
-        // Read paths and discovery — never staged.
+        // Read paths and discovery.
         ToolCategory::Safe | ToolCategory::McpRead => RiskLevel::Benign,
         // Query-only network is benign; opening a URL pulls arbitrary
         // remote content, so it stays destructive.
@@ -448,9 +446,7 @@ fn build_impact_summary_zh_hans(
     }
 }
 
-/// Indices into the option list shared by both variants. Visible to
-/// the widget module so it can render the staged-confirmation banner
-/// without re-deriving the variant from the request.
+/// Indices into the option list shared by both variants.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ApprovalOption {
     ApproveOnce,
@@ -486,16 +482,6 @@ impl ApprovalOption {
             ApprovalOption::Abort => ReviewDecision::Abort,
         }
     }
-
-    /// Whether this option needs an explicit second-key confirmation in
-    /// the destructive variant. Deny/Abort are never staged.
-    fn requires_confirm(self, risk: RiskLevel) -> bool {
-        matches!(risk, RiskLevel::Destructive)
-            && matches!(
-                self,
-                ApprovalOption::ApproveOnce | ApprovalOption::ApproveAlways
-            )
-    }
 }
 
 /// Approval overlay state managed by the modal view stack
@@ -504,10 +490,6 @@ pub struct ApprovalView {
     request: ApprovalRequest,
     selected: usize,
     locale: Locale,
-    /// When `Some`, the destructive variant has staged this approval and
-    /// is waiting for the user to press the same key (or `Enter`) again.
-    /// Any other key clears the staging.
-    pending_confirm: Option<ApprovalOption>,
     timeout: Option<Duration>,
     requested_at: Instant,
     /// Whether the approval card is collapsed to a single-line banner.
@@ -525,7 +507,6 @@ impl ApprovalView {
             request,
             selected: 0,
             locale,
-            pending_confirm: None,
             timeout: None,
             requested_at: Instant::now(),
             collapsed: false,
@@ -534,22 +515,17 @@ impl ApprovalView {
 
     fn select_prev(&mut self) {
         self.selected = self.selected.saturating_sub(1);
-        // Moving the selection abandons any staged confirmation; the
-        // user is reconsidering.
-        self.pending_confirm = None;
     }
 
     fn select_next(&mut self) {
         self.selected = (self.selected + 1).min(ApprovalOption::ORDER.len() - 1);
-        self.pending_confirm = None;
     }
 
     fn current_option(&self) -> ApprovalOption {
         ApprovalOption::from_index(self.selected)
     }
 
-    /// Test-only accessor — the widget reads decisions through
-    /// `commit_or_stage` instead of polling.
+    /// Test-only accessor for the selected option's decision.
     #[cfg(test)]
     fn current_decision(&self) -> ReviewDecision {
         self.current_option().decision()
@@ -566,33 +542,13 @@ impl ApprovalView {
         self.request.risk
     }
 
-    /// The staged option, if any. `None` in the benign variant or when
-    /// no approve key has been pressed yet.
-    pub(crate) fn pending_confirm(&self) -> Option<ApprovalOption> {
-        self.pending_confirm
-    }
-
     pub(crate) fn locale(&self) -> Locale {
         self.locale
     }
 
-    /// Try to commit (or stage) the given option respecting the
-    /// variant's confirmation policy. Returns the action the modal
-    /// stack should apply.
-    fn commit_or_stage(&mut self, option: ApprovalOption) -> ViewAction {
-        if option.requires_confirm(self.request.risk) {
-            // Two-step destructive flow: first press stages, second
-            // press of the same option commits.
-            if self.pending_confirm == Some(option) {
-                self.pending_confirm = None;
-                return self.emit_decision(option.decision(), false);
-            }
-            self.pending_confirm = Some(option);
-            self.selected = option.index();
-            return ViewAction::None;
-        }
-        // Benign variant or non-approve options commit immediately.
-        self.pending_confirm = None;
+    /// Commit the given option and close the approval modal.
+    fn commit_option(&mut self, option: ApprovalOption) -> ViewAction {
+        self.selected = option.index();
         self.emit_decision(option.decision(), false)
     }
 
@@ -647,31 +603,23 @@ impl ModalView for ApprovalView {
                 self.select_next();
                 ViewAction::None
             }
-            KeyCode::Enter => self.commit_or_stage(self.current_option()),
+            KeyCode::Enter => self.commit_option(self.current_option()),
             // Direct shortcuts; '1' / '2' map to the first two options
-            // so a numeric pad still works for benign approve flows.
+            // so a numeric pad still works for approve flows.
             KeyCode::Char('y') | KeyCode::Char('Y') | KeyCode::Char('1') => {
-                self.commit_or_stage(ApprovalOption::ApproveOnce)
+                self.commit_option(ApprovalOption::ApproveOnce)
             }
             KeyCode::Char('a') | KeyCode::Char('A') | KeyCode::Char('2') => {
-                self.commit_or_stage(ApprovalOption::ApproveAlways)
+                self.commit_option(ApprovalOption::ApproveAlways)
             }
             KeyCode::Char('n')
             | KeyCode::Char('N')
             | KeyCode::Char('d')
             | KeyCode::Char('D')
-            | KeyCode::Char('3') => self.commit_or_stage(ApprovalOption::Deny),
-            KeyCode::Char('v') | KeyCode::Char('V') => {
-                self.pending_confirm = None;
-                self.emit_params_pager()
-            }
+            | KeyCode::Char('3') => self.commit_option(ApprovalOption::Deny),
+            KeyCode::Char('v') | KeyCode::Char('V') => self.emit_params_pager(),
             KeyCode::Esc => self.emit_decision(ReviewDecision::Abort, false),
-            _ => {
-                // Any unrecognised key cancels a staged confirmation —
-                // the user is no longer aiming at "approve".
-                self.pending_confirm = None;
-                ViewAction::None
-            }
+            _ => ViewAction::None,
         }
     }
 
@@ -1030,13 +978,13 @@ mod tests {
 
     #[test]
     fn risk_query_only_network_is_benign_but_fetch_is_destructive() {
-        // web_search is read-only enough to skip the two-key dance.
+        // web_search is read-only enough to use the benign variant.
         let cat = ToolCategory::Network;
         assert_eq!(
             classify_risk("web_search", cat, &json!({"q": "rust"})),
             RiskLevel::Benign
         );
-        // fetch_url pulls arbitrary remote content; never staged.
+        // fetch_url pulls arbitrary remote content, so it stays destructive.
         assert_eq!(
             classify_risk("fetch_url", cat, &json!({"url": "https://example.com"})),
             RiskLevel::Destructive
@@ -1163,7 +1111,6 @@ mod tests {
         let view = ApprovalView::new(benign_request());
         assert_eq!(view.selected, 0);
         assert!(view.timeout.is_none());
-        assert_eq!(view.pending_confirm(), None);
         assert_eq!(view.risk(), RiskLevel::Benign);
     }
 
@@ -1376,7 +1323,7 @@ mod tests {
     }
 
     // ========================================================================
-    // ApprovalView Tests — Destructive Variant (two-key confirm)
+    // ApprovalView Tests — Destructive Variant (one-step approve with warning)
     // ========================================================================
 
     #[test]
@@ -1386,16 +1333,10 @@ mod tests {
     }
 
     #[test]
-    fn destructive_y_first_press_stages_then_second_commits() {
+    fn destructive_y_first_press_approves_once() {
         for code in [KeyCode::Char('y'), KeyCode::Char('Y')] {
             let mut view = ApprovalView::new(destructive_request());
 
-            // First press stages — no decision emitted yet.
-            let action = view.handle_key(create_key_event(code));
-            assert!(matches!(action, ViewAction::None));
-            assert_eq!(view.pending_confirm(), Some(ApprovalOption::ApproveOnce));
-
-            // Second press of the same key commits.
             let action = view.handle_key(create_key_event(code));
             assert!(
                 matches!(
@@ -1411,15 +1352,10 @@ mod tests {
     }
 
     #[test]
-    fn destructive_enter_first_press_stages_then_second_commits() {
+    fn destructive_enter_approves_selected_option() {
         let mut view = ApprovalView::new(destructive_request());
 
-        // Selection starts at ApproveOnce — Enter stages.
-        let action = view.handle_key(create_key_event(KeyCode::Enter));
-        assert!(matches!(action, ViewAction::None));
-        assert_eq!(view.pending_confirm(), Some(ApprovalOption::ApproveOnce));
-
-        // Second Enter on the same selection commits.
+        // Selection starts at ApproveOnce — Enter commits the selected option.
         let action = view.handle_key(create_key_event(KeyCode::Enter));
         assert!(matches!(
             action,
@@ -1431,39 +1367,33 @@ mod tests {
     }
 
     #[test]
-    fn destructive_navigation_clears_staged_confirmation() {
+    fn destructive_navigation_then_enter_commits_highlighted_option() {
         let mut view = ApprovalView::new(destructive_request());
 
-        view.handle_key(create_key_event(KeyCode::Char('y')));
-        assert_eq!(view.pending_confirm(), Some(ApprovalOption::ApproveOnce));
-
-        // Moving the selection abandons the staging.
         view.handle_key(create_key_event(KeyCode::Down));
-        assert_eq!(view.pending_confirm(), None);
+        let action = view.handle_key(create_key_event(KeyCode::Enter));
+        assert!(matches!(
+            action,
+            ViewAction::EmitAndClose(ViewEvent::ApprovalDecision {
+                decision: ReviewDecision::ApprovedForSession,
+                ..
+            })
+        ));
     }
 
     #[test]
-    fn destructive_unrelated_key_clears_staged_confirmation() {
+    fn destructive_unrelated_key_keeps_modal_open() {
         let mut view = ApprovalView::new(destructive_request());
 
-        view.handle_key(create_key_event(KeyCode::Char('y')));
-        assert_eq!(view.pending_confirm(), Some(ApprovalOption::ApproveOnce));
-
-        // A key with no mapped action clears the staging.
         let action = view.handle_key(create_key_event(KeyCode::Char('q')));
         assert!(matches!(action, ViewAction::None));
-        assert_eq!(view.pending_confirm(), None);
     }
 
     #[test]
-    fn destructive_a_first_press_stages_then_second_commits_session() {
+    fn destructive_a_first_press_approves_for_session() {
         for code in [KeyCode::Char('a'), KeyCode::Char('A')] {
             let mut view = ApprovalView::new(destructive_request());
 
-            let action = view.handle_key(create_key_event(code));
-            assert!(matches!(action, ViewAction::None));
-            assert_eq!(view.pending_confirm(), Some(ApprovalOption::ApproveAlways));
-
             let action = view.handle_key(create_key_event(code));
             assert!(
                 matches!(
@@ -1479,23 +1409,8 @@ mod tests {
     }
 
     #[test]
-    fn destructive_y_then_a_does_not_commit_either() {
-        // Pressing 'y' then 'a' must NOT commit ApproveAlways — the
-        // second key is a different option, so it re-stages instead.
-        let mut view = ApprovalView::new(destructive_request());
-
-        let action = view.handle_key(create_key_event(KeyCode::Char('y')));
-        assert!(matches!(action, ViewAction::None));
-        assert_eq!(view.pending_confirm(), Some(ApprovalOption::ApproveOnce));
-
-        let action = view.handle_key(create_key_event(KeyCode::Char('a')));
-        assert!(matches!(action, ViewAction::None));
-        assert_eq!(view.pending_confirm(), Some(ApprovalOption::ApproveAlways));
-    }
-
-    #[test]
-    fn destructive_deny_does_not_require_confirmation() {
-        // Deny / Abort skip the two-key dance — the user is bailing.
+    fn destructive_deny_commits_immediately() {
+        // Deny commits immediately — the user is rejecting the tool.
         for code in [
             KeyCode::Char('n'),
             KeyCode::Char('N'),
@@ -1520,9 +1435,6 @@ mod tests {
     #[test]
     fn destructive_esc_aborts_immediately() {
         let mut view = ApprovalView::new(destructive_request());
-        // Stage something first.
-        view.handle_key(create_key_event(KeyCode::Char('y')));
-        // Esc still aborts in one press.
         let action = view.handle_key(create_key_event(KeyCode::Esc));
         assert!(matches!(
             action,
@@ -1557,20 +1469,21 @@ mod tests {
     }
 
     #[test]
-    fn render_benign_includes_review_badge_and_one_step_hint() {
+    fn render_benign_includes_review_badge_and_selection_hint() {
         let view = ApprovalView::new(benign_request());
         let lines = render_lines(&view, 100, 40);
         let joined = lines.join("\n");
         assert!(joined.contains("REVIEW"), "missing REVIEW badge:\n{joined}");
+        assert!(joined.contains("Choose"), "benign hint missing:\n{joined}");
         assert!(
-            joined.contains("Single key approves"),
-            "benign hint missing:\n{joined}"
+            joined.contains("Enter selected option"),
+            "benign selection hint missing:\n{joined}"
         );
         assert!(joined.contains("read_file"));
     }
 
     #[test]
-    fn render_destructive_shows_warning_badge_and_two_step_hint() {
+    fn render_destructive_shows_warning_badge_and_one_step_hint() {
         let view = ApprovalView::new(destructive_request());
         let lines = render_lines(&view, 100, 40);
         let joined = lines.join("\n");
@@ -1579,31 +1492,15 @@ mod tests {
             "missing DESTRUCTIVE badge:\n{joined}"
         );
         assert!(
-            joined.contains("Two keys to approve"),
+            joined.contains("Enter selected option"),
             "destructive hint missing:\n{joined}"
         );
         assert!(joined.contains("write_file"));
     }
 
-    #[test]
-    fn render_destructive_after_stage_shows_confirm_banner() {
-        let mut view = ApprovalView::new(destructive_request());
-        view.handle_key(create_key_event(KeyCode::Char('y')));
-        let lines = render_lines(&view, 100, 40);
-        let joined = lines.join("\n");
-        assert!(
-            joined.contains("Confirm destructive action"),
-            "confirm banner missing:\n{joined}"
-        );
-        assert!(
-            joined.contains("(staged)"),
-            "stage marker missing:\n{joined}"
-        );
-    }
-
     #[test]
     fn render_destructive_zh_hans_localizes_security_copy() {
-        let mut view = ApprovalView::new_for_locale(destructive_request(), Locale::ZhHans);
+        let view = ApprovalView::new_for_locale(destructive_request(), Locale::ZhHans);
         let lines = render_lines(&view, 100, 40);
         let joined = compact_rendered_text(&lines);
         assert!(
@@ -1611,8 +1508,12 @@ mod tests {
             "missing zh risk badge:\n{joined}"
         );
         assert!(
-            joined.contains("两次按键确认"),
-            "missing zh two-step hint:\n{joined}"
+            joined.contains("选择："),
+            "missing zh selection prefix:\n{joined}"
+        );
+        assert!(
+            joined.contains("Enter执行选中项，或直接按y/a/d"),
+            "missing zh one-step hint:\n{joined}"
         );
         assert!(
             joined.contains("文件写入"),
@@ -1630,22 +1531,6 @@ mod tests {
             joined.contains("仅本次批准"),
             "missing zh approve option:\n{joined}"
         );
-
-        view.handle_key(create_key_event(KeyCode::Char('y')));
-        let lines = render_lines(&view, 100, 40);
-        let joined = compact_rendered_text(&lines);
-        assert!(
-            joined.contains("确认破坏性操作"),
-            "missing zh confirm banner:\n{joined}"
-        );
-        assert!(
-            joined.contains("(待确认)"),
-            "missing zh staged marker:\n{joined}"
-        );
-        assert!(
-            joined.contains("Enter或y"),
-            "missing zh confirm key:\n{joined}"
-        );
     }
 
     #[test]
diff --git a/crates/tui/src/tui/clipboard.rs b/crates/tui/src/tui/clipboard.rs
index 2eadfd0f..bbefcac8 100644
--- a/crates/tui/src/tui/clipboard.rs
+++ b/crates/tui/src/tui/clipboard.rs
@@ -279,7 +279,7 @@ fn osc52_sequence(text: &str, in_tmux: bool) -> Result<String> {
 /// `<workspace>/clipboard-images/` if the home dir is unavailable.
 pub(crate) fn clipboard_images_dir(workspace: &Path) -> PathBuf {
     if let Some(home) = dirs::home_dir() {
-        return home.join(".deepseek").join("clipboard-images");
+        return home.join(".codewhale").join("clipboard-images");
     }
     workspace.join("clipboard-images")
 }
@@ -442,7 +442,12 @@ mod tests {
     #[cfg(target_os = "linux")]
     #[test]
     fn wlcopy_helper_succeeds_when_binary_returns_zero() {
-        let result = write_text_with_wlcopy_using_argv("true", "test");
+        // Use `cat` instead of `true` because `true` exits immediately
+        // without reading stdin, causing EPIPE before we can check the
+        // exit status.  `cat` consumes stdin until EOF (when we drop the
+        // pipe) and then exits 0, faithfully modelling a successful
+        // wl-copy invocation.
+        let result = write_text_with_wlcopy_using_argv("cat", "test");
         assert!(result.is_ok());
     }
 
diff --git a/crates/tui/src/tui/color_compat.rs b/crates/tui/src/tui/color_compat.rs
index 68c367f2..cedaea0b 100644
--- a/crates/tui/src/tui/color_compat.rs
+++ b/crates/tui/src/tui/color_compat.rs
@@ -6,6 +6,8 @@
 //! as stray green/cyan backgrounds. This backend adapts every cell to the
 //! detected color depth before handing it to crossterm.
 
+use std::fmt::Write as _;
+use std::fs::{self, File, OpenOptions};
 use std::io::{self, Write};
 
 use ratatui::{
@@ -16,6 +18,9 @@ use ratatui::{
 
 use crate::palette::{self, ColorDepth, PaletteMode, ThemeId, UiTheme};
 
+const RENDER_DEBUG_ENV: &str = "CODEWHALE_TUI_DEBUG";
+const RENDER_DEBUG_SAMPLE_LIMIT: usize = 24;
+
 #[derive(Debug)]
 pub(crate) struct ColorCompatBackend<W: Write> {
     inner: CrosstermBackend<W>,
@@ -38,6 +43,7 @@ pub(crate) struct ColorCompatBackend<W: Write> {
     /// Forcing the expected size prevents ratatui's internal `autoresize` from
     /// shrinking the viewport back to the stale dimension inside `draw()`.
     forced_size: Option<Size>,
+    render_debug: Option<RenderDebugLog>,
 }
 
 impl<W: Write> ColorCompatBackend<W> {
@@ -53,6 +59,7 @@ impl<W: Write> ColorCompatBackend<W> {
             // to a community preset.
             active_ui_theme: UiTheme::detect(),
             forced_size: None,
+            render_debug: RenderDebugLog::from_env(),
         }
     }
 
@@ -104,6 +111,14 @@ impl<W: Write> Backend for ColorCompatBackend<W> {
                 (x, y, cell)
             })
             .collect::<Vec<_>>();
+        let viewport = if self.render_debug.is_some() {
+            self.size().ok()
+        } else {
+            None
+        };
+        if let Some(render_debug) = &mut self.render_debug {
+            render_debug.record(viewport, &adapted);
+        }
         self.inner
             .draw(adapted.iter().map(|(x, y, cell)| (*x, *y, cell)))
     }
@@ -152,6 +167,88 @@ impl<W: Write> Backend for ColorCompatBackend<W> {
     }
 }
 
+#[derive(Debug)]
+struct RenderDebugLog {
+    file: File,
+    frame: u64,
+}
+
+impl RenderDebugLog {
+    fn from_env() -> Option<Self> {
+        if !render_debug_enabled_from_value(std::env::var(RENDER_DEBUG_ENV).ok().as_deref()) {
+            return None;
+        }
+
+        let log_dir = crate::runtime_log::log_directory()?;
+        if let Err(err) = fs::create_dir_all(&log_dir) {
+            tracing::debug!(?err, "failed to create TUI render debug log directory");
+            return None;
+        }
+        let path = log_dir.join("tui-render.log");
+        let file = OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&path)
+            .map_err(|err| {
+                tracing::debug!(?err, path = %path.display(), "failed to open TUI render debug log");
+                err
+            })
+            .ok()?;
+
+        Some(Self { file, frame: 0 })
+    }
+
+    fn record(&mut self, viewport: Option<Size>, diff: &[(u16, u16, Cell)]) {
+        self.frame = self.frame.saturating_add(1);
+        let sample = diff
+            .iter()
+            .take(RENDER_DEBUG_SAMPLE_LIMIT)
+            .map(|(x, y, _)| (*x, *y))
+            .collect::<Vec<_>>();
+        let line = render_debug_line(self.frame, viewport, diff.len(), &sample);
+        let _ = self.file.write_all(line.as_bytes());
+    }
+}
+
+fn render_debug_enabled_from_value(value: Option<&str>) -> bool {
+    matches!(
+        value.map(str::trim).map(str::to_ascii_lowercase).as_deref(),
+        Some("1" | "true" | "yes" | "on")
+    )
+}
+
+fn render_debug_line(
+    frame: u64,
+    viewport: Option<Size>,
+    diff_cells: usize,
+    sample: &[(u16, u16)],
+) -> String {
+    let mut line = String::new();
+    match viewport {
+        Some(size) => {
+            let _ = write!(
+                &mut line,
+                "frame={frame} size={}x{} diff_cells={diff_cells} sample=",
+                size.width, size.height
+            );
+        }
+        None => {
+            let _ = write!(
+                &mut line,
+                "frame={frame} size=unknown diff_cells={diff_cells} sample="
+            );
+        }
+    }
+    for (index, (x, y)) in sample.iter().enumerate() {
+        if index > 0 {
+            line.push(',');
+        }
+        let _ = write!(&mut line, "{x}:{y}");
+    }
+    line.push('\n');
+    line
+}
+
 fn adapt_cell_colors(
     cell: &mut Cell,
     depth: ColorDepth,
@@ -177,12 +274,13 @@ fn adapt_cell_colors(
 
 #[cfg(test)]
 mod tests {
-    use std::{cell::RefCell, io::Write, rc::Rc};
+    use std::{cell::RefCell, env, ffi::OsString, fs, io::Write, rc::Rc};
 
     use ratatui::backend::Backend;
     use ratatui::{buffer::Cell, style::Color};
 
     use super::*;
+    use crate::test_support::lock_test_env;
 
     #[derive(Clone, Default)]
     struct SharedWriter(Rc<RefCell<Vec<u8>>>);
@@ -198,6 +296,32 @@ mod tests {
         }
     }
 
+    struct EnvRestore {
+        key: &'static str,
+        value: Option<OsString>,
+    }
+
+    impl EnvRestore {
+        fn capture(key: &'static str) -> Self {
+            Self {
+                key,
+                value: env::var_os(key),
+            }
+        }
+    }
+
+    impl Drop for EnvRestore {
+        fn drop(&mut self) {
+            // SAFETY: environment mutation is serialized by lock_test_env.
+            unsafe {
+                match &self.value {
+                    Some(value) => env::set_var(self.key, value),
+                    None => env::remove_var(self.key),
+                }
+            }
+        }
+    }
+
     #[test]
     fn adapts_rgb_cells_to_indexed_on_ansi256() {
         let mut cell = Cell::default();
@@ -255,7 +379,7 @@ mod tests {
     fn light_palette_maps_dark_cells_before_depth_adaptation() {
         let mut cell = Cell::default();
         cell.set_fg(Color::White);
-        cell.set_bg(Color::Rgb(11, 21, 38));
+        cell.set_bg(palette::DEEPSEEK_INK);
 
         adapt_cell_colors(
             &mut cell,
@@ -318,4 +442,58 @@ mod tests {
         backend.set_palette_mode(PaletteMode::Grayscale);
         assert_eq!(backend.palette_mode, PaletteMode::Grayscale);
     }
+
+    #[test]
+    fn render_debug_env_parser_accepts_truthy_values_only() {
+        assert!(!render_debug_enabled_from_value(None));
+        assert!(!render_debug_enabled_from_value(Some("")));
+        assert!(!render_debug_enabled_from_value(Some("0")));
+        assert!(!render_debug_enabled_from_value(Some("false")));
+        assert!(render_debug_enabled_from_value(Some("1")));
+        assert!(render_debug_enabled_from_value(Some("true")));
+        assert!(render_debug_enabled_from_value(Some("YES")));
+        assert!(render_debug_enabled_from_value(Some("on")));
+    }
+
+    #[test]
+    fn render_debug_line_records_frame_size_and_diff_sample() {
+        let line = render_debug_line(7, Some(Size::new(80, 24)), 42, &[(0, 0), (12, 3), (79, 23)]);
+
+        assert_eq!(
+            line,
+            "frame=7 size=80x24 diff_cells=42 sample=0:0,12:3,79:23\n"
+        );
+    }
+
+    #[test]
+    fn backend_writes_render_debug_log_when_enabled() {
+        let _lock = lock_test_env();
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let _home = EnvRestore::capture("HOME");
+        let _userprofile = EnvRestore::capture("USERPROFILE");
+        let _debug = EnvRestore::capture(RENDER_DEBUG_ENV);
+
+        // SAFETY: environment mutation is serialized by lock_test_env.
+        unsafe {
+            env::set_var("HOME", tmp.path());
+            env::set_var("USERPROFILE", "");
+            env::set_var(RENDER_DEBUG_ENV, "1");
+        }
+
+        let writer = SharedWriter::default();
+        let mut backend = ColorCompatBackend::new(writer, ColorDepth::TrueColor, PaletteMode::Dark);
+        let mut cell = Cell::default();
+        cell.set_symbol("x");
+        backend.draw(std::iter::once((3, 4, &cell))).unwrap();
+
+        let log_path = tmp
+            .path()
+            .join(".codewhale")
+            .join("logs")
+            .join("tui-render.log");
+        let body = fs::read_to_string(log_path).expect("render debug log");
+        assert!(body.contains("frame=1"), "{body}");
+        assert!(body.contains("diff_cells=1"), "{body}");
+        assert!(body.contains("sample=3:4"), "{body}");
+    }
 }
diff --git a/crates/tui/src/tui/command_palette.rs b/crates/tui/src/tui/command_palette.rs
index 4af59bcf..f1e5bb04 100644
--- a/crates/tui/src/tui/command_palette.rs
+++ b/crates/tui/src/tui/command_palette.rs
@@ -55,14 +55,6 @@ pub fn build_entries(
 ) -> Vec<CommandPaletteEntry> {
     let mut entries = Vec::new();
 
-    entries.push(CommandPaletteEntry {
-        section: PaletteSection::Action,
-        label: "Voice input".to_string(),
-        description: "Listen, transcribe, and insert editable text into the composer".to_string(),
-        command: "voice input dictate microphone speech".to_string(),
-        action: CommandPaletteAction::VoiceInput,
-    });
-
     for command in commands::COMMANDS {
         let mut description = command.palette_description_for(locale);
         if command.requires_argument() {
@@ -1017,24 +1009,6 @@ mod tests {
         assert!(!command_labels.contains(&"/deepseek"));
     }
 
-    #[test]
-    fn command_palette_includes_voice_input_action() {
-        let entries = build_entries(
-            Locale::En,
-            Path::new("."),
-            Path::new("."),
-            Path::new("mcp.json"),
-            None,
-        );
-        let voice = entries
-            .iter()
-            .find(|entry| entry.section == PaletteSection::Action && entry.label == "Voice input")
-            .expect("voice input action");
-
-        assert!(voice.description.contains("composer"));
-        assert!(matches!(voice.action, CommandPaletteAction::VoiceInput));
-    }
-
     #[test]
     fn command_palette_inserts_model_command_for_argument_entry() {
         let entries = build_entries(
diff --git a/crates/tui/src/tui/context_menu.rs b/crates/tui/src/tui/context_menu.rs
index e897577c..20543551 100644
--- a/crates/tui/src/tui/context_menu.rs
+++ b/crates/tui/src/tui/context_menu.rs
@@ -28,16 +28,18 @@ pub struct ContextMenuView {
     column: u16,
     row: u16,
     last_rect: Cell<Option<Rect>>,
+    title: String,
 }
 
 impl ContextMenuView {
-    pub fn new(entries: Vec<ContextMenuEntry>, column: u16, row: u16) -> Self {
+    pub fn new(entries: Vec<ContextMenuEntry>, column: u16, row: u16, title: String) -> Self {
         Self {
             entries,
             selected: 0,
             column,
             row,
             last_rect: Cell::new(None),
+            title,
         }
     }
 
@@ -199,7 +201,7 @@ impl ModalView for ContextMenuView {
             .collect::<Vec<_>>();
 
         let block = Block::default()
-            .title(" Right click ")
+            .title(self.title.as_str())
             .borders(Borders::ALL)
             .border_style(Style::default().fg(palette::DEEPSEEK_SKY))
             .style(Style::default().bg(palette::SURFACE_ELEVATED))
@@ -256,6 +258,7 @@ mod tests {
             ],
             5,
             5,
+            " Right click ".to_string(),
         );
 
         view.handle_key(KeyEvent::new(KeyCode::Down, KeyModifiers::NONE));
@@ -271,7 +274,12 @@ mod tests {
 
     #[test]
     fn menu_clamps_to_render_area() {
-        let view = ContextMenuView::new(vec![entry("Paste", ContextMenuAction::Paste)], 200, 80);
+        let view = ContextMenuView::new(
+            vec![entry("Paste", ContextMenuAction::Paste)],
+            200,
+            80,
+            " Right click ".to_string(),
+        );
 
         let rect = view.menu_rect(Rect {
             x: 0,
@@ -293,6 +301,7 @@ mod tests {
             ],
             2,
             2,
+            " Right click ".to_string(),
         );
         let area = Rect {
             x: 0,
diff --git a/crates/tui/src/tui/file_frecency.rs b/crates/tui/src/tui/file_frecency.rs
index 5129d695..10b83852 100644
--- a/crates/tui/src/tui/file_frecency.rs
+++ b/crates/tui/src/tui/file_frecency.rs
@@ -55,7 +55,7 @@ fn store() -> &'static Mutex<Store> {
 }
 
 fn default_path() -> Option<PathBuf> {
-    dirs::home_dir().map(|h| h.join(".deepseek").join("file-frecency.jsonl"))
+    dirs::home_dir().map(|h| h.join(".codewhale").join("file-frecency.jsonl"))
 }
 
 fn now_secs() -> u64 {
diff --git a/crates/tui/src/tui/file_picker.rs b/crates/tui/src/tui/file_picker.rs
index ef21091e..76b05d15 100644
--- a/crates/tui/src/tui/file_picker.rs
+++ b/crates/tui/src/tui/file_picker.rs
@@ -24,6 +24,7 @@ use ratatui::{
 
 use crate::palette;
 use crate::tui::views::{ModalKind, ModalView, ViewAction, ViewEvent};
+use crate::workspace_discovery::{DISCOVERY_ALWAYS_DIRS, path_is_excluded_from_discovery};
 
 /// Maximum number of candidates collected from the initial walk. Keeps memory
 /// bounded for very large monorepos; matches the limits codex-rs uses for the
@@ -437,7 +438,7 @@ fn collect_candidates(root: &Path) -> Vec<String> {
 
     // Whitelist AI-tool dot-directories so they're discoverable even when
     // gitignored. Walk each one separately with gitignore disabled.
-    for dir in [".deepseek", ".cursor", ".claude", ".agents"] {
+    for dir in DISCOVERY_ALWAYS_DIRS {
         let dot_dir = root.join(dir);
         if !dot_dir.is_dir() {
             continue;
@@ -451,7 +452,7 @@ fn collect_candidates(root: &Path) -> Vec<String> {
             .max_depth(Some(WALK_DEPTH.saturating_sub(1)));
         for entry in dot_builder.build().flatten() {
             // Exclude machine-generated bulk (e.g. .deepseek/snapshots/).
-            if entry.path().starts_with(root.join(".deepseek/snapshots")) {
+            if path_is_excluded_from_discovery(root, entry.path()) {
                 continue;
             }
             if !entry.file_type().is_some_and(|ft| ft.is_file()) {
@@ -733,4 +734,58 @@ mod tests {
             "skipme.txt should be filtered by .ignore: {visible:?}"
         );
     }
+
+    #[test]
+    fn picker_skips_generated_worktree_bulk_inside_unignored_dot_dirs() {
+        let dir = TempDir::new().expect("tempdir");
+        let root = dir.path();
+        fs::create_dir_all(root.join("src")).unwrap();
+        fs::write(root.join("src/main.rs"), "fn main() {}").unwrap();
+
+        fs::create_dir_all(root.join(".deepseek/commands")).unwrap();
+        fs::write(root.join(".deepseek/commands/build.md"), "build").unwrap();
+        fs::create_dir_all(root.join(".deepseek/snapshots/deadbeef/.git/objects")).unwrap();
+        fs::write(
+            root.join(".deepseek/snapshots/deadbeef/.git/objects/snapshot.pack"),
+            "pack",
+        )
+        .unwrap();
+
+        fs::create_dir_all(root.join(".claude/commands")).unwrap();
+        fs::write(root.join(".claude/commands/test.md"), "test").unwrap();
+        fs::create_dir_all(root.join(".claude/worktrees/agent/src")).unwrap();
+        fs::write(
+            root.join(".claude/worktrees/agent/src/agent-only.md"),
+            "agent",
+        )
+        .unwrap();
+
+        let candidates = collect_candidates(root);
+
+        assert!(candidates.iter().any(|path| path == "src/main.rs"));
+        assert!(
+            candidates
+                .iter()
+                .any(|path| path == ".deepseek/commands/build.md"),
+            "normal .deepseek command files should stay discoverable: {candidates:?}",
+        );
+        assert!(
+            candidates
+                .iter()
+                .any(|path| path == ".claude/commands/test.md"),
+            "normal .claude command files should stay discoverable: {candidates:?}",
+        );
+        assert!(
+            candidates
+                .iter()
+                .all(|path| !path.starts_with(".deepseek/snapshots/")),
+            "snapshot side repo files must not enter picker candidates: {candidates:?}",
+        );
+        assert!(
+            candidates
+                .iter()
+                .all(|path| !path.starts_with(".claude/worktrees/")),
+            ".claude worktree files must not enter picker candidates: {candidates:?}",
+        );
+    }
 }
diff --git a/crates/tui/src/tui/footer_ui.rs b/crates/tui/src/tui/footer_ui.rs
index 3b0c3ebd..a3af6647 100644
--- a/crates/tui/src/tui/footer_ui.rs
+++ b/crates/tui/src/tui/footer_ui.rs
@@ -71,11 +71,22 @@ pub(crate) fn render_footer(f: &mut Frame, area: Rect, app: &mut App) {
         let dot_frame = footer_working_label_frame(now_ms, app.fancy_animations);
         // Surface one compact live status row in the footer whenever a turn
         // is live. Tool turns get the current action plus active/done counts;
-        // non-tool work falls back to the existing dot-pulse label.
-        let mut label = active_voice_input_status_label(app, now_ms)
-            .or_else(|| active_subagent_status_label(app))
+        // non-tool work falls back to a descriptive label with elapsed time.
+        let elapsed_secs = app
+            .turn_started_at
+            .map(|t| t.elapsed().as_secs())
+            .unwrap_or(0);
+        let mut label = active_subagent_status_label(app)
             .or_else(|| active_tool_status_label(app))
-            .unwrap_or_else(|| crate::tui::widgets::footer_working_label(dot_frame, app.ui_locale));
+            .unwrap_or_else(|| {
+                // Show the working label during active turns (loading, compacting, etc.).
+                let base = crate::tui::widgets::footer_working_label(dot_frame, app.ui_locale);
+                if elapsed_secs > 0 {
+                    format!("{base} ({elapsed_secs}s)")
+                } else {
+                    base.to_string()
+                }
+            });
         // Append stall reason when the turn has been running > 30 s.
         if let Some(reason) = stall_reason(app) {
             label = format!("{label}  ({reason})");
@@ -158,45 +169,18 @@ pub(crate) fn footer_working_strip_active(app: &App) -> bool {
     let turn_in_progress = app.runtime_turn_status.as_deref() == Some("in_progress");
     app.is_loading
         || app.is_compacting
+        || app.is_purging
         || running_agent_count(app) > 0
         || turn_in_progress
-        || app.voice_input_state.is_some()
 }
 
 pub(crate) fn footer_working_label_frame(now_ms: u64, fancy_animations: bool) -> u64 {
     if fancy_animations { now_ms / 400 } else { 0 }
 }
 
-pub(crate) fn active_voice_input_status_label(app: &App, now_ms: u64) -> Option<String> {
-    let state = app.voice_input_state.as_ref()?;
-    let elapsed = state.started_at.elapsed().as_secs();
-    Some(voice_input_status_text(
-        app.fancy_animations,
-        elapsed,
-        now_ms,
-    ))
-}
-
-pub(crate) fn voice_input_status_text(
-    fancy_animations: bool,
-    elapsed_secs: u64,
-    now_ms: u64,
-) -> String {
-    if !fancy_animations {
-        return format!("listening/transcribing {elapsed_secs}s");
-    }
-    let dots = match (now_ms / 300) % 4 {
-        0 => "",
-        1 => ".",
-        2 => "..",
-        _ => "...",
-    };
-    format!("listening/transcribing{dots} {elapsed_secs}s")
-}
-
 #[cfg(test)]
 mod tests {
-    use super::{footer_working_label_frame, voice_input_status_text};
+    use super::footer_working_label_frame;
 
     #[test]
     fn footer_working_label_frame_is_static_without_fancy_animations() {
@@ -205,15 +189,6 @@ mod tests {
         assert_eq!(footer_working_label_frame(1_600, false), 0);
         assert_eq!(footer_working_label_frame(1_600, true), 4);
     }
-
-    #[test]
-    fn voice_input_status_label_animates_when_enabled() {
-        let first = voice_input_status_text(true, 2, 0);
-        let second = voice_input_status_text(true, 2, 300);
-
-        assert_ne!(first, second);
-        assert!(first.contains("listening/transcribing"));
-    }
 }
 
 pub(crate) fn is_noisy_subagent_progress(status: &str) -> bool {
@@ -508,9 +483,16 @@ pub(crate) fn render_footer_from(
         props.model.clear();
     }
 
+    // Shell-running chip: visible whenever a foreground shell command is
+    // active, regardless of user-configured status items.
+    let shell_chip = crate::tui::widgets::footer_shell_chip(active_foreground_shell_running(app));
+
     // Right-cluster extension chips: append in `items` order so user
     // ordering is preserved across the new variants.
     let mut extra: Vec<Span<'static>> = Vec::new();
+    if !shell_chip.is_empty() {
+        extra.extend(shell_chip);
+    }
     for item in items {
         let chip = match *item {
             S::PrefixStability => prefix_stability.clone(),
@@ -518,6 +500,7 @@ pub(crate) fn render_footer_from(
             S::ContextPercent => footer_context_percent_spans(app),
             S::GitBranch => footer_git_branch_spans(app),
             S::LastToolElapsed | S::RateLimit => Vec::new(),
+            S::Tokens => footer_session_tokens_spans(app),
             _ => continue,
         };
         if chip.is_empty() {
@@ -543,11 +526,15 @@ pub(crate) fn render_footer_from(
 }
 
 pub(crate) fn footer_git_branch_spans(app: &App) -> Vec<Span<'static>> {
-    let Some(branch) = workspace_context::branch(&app.workspace) else {
+    let Some(branch) = app
+        .workspace_context
+        .as_deref()
+        .and_then(workspace_context::branch_from_context)
+    else {
         return Vec::new();
     };
     vec![Span::styled(
-        branch,
+        branch.to_string(),
         Style::default().fg(app.ui_theme.text_muted),
     )]
 }
@@ -583,16 +570,48 @@ pub(crate) fn footer_cost_spans(app: &App) -> Vec<Span<'static>> {
     if !should_show_footer_cost(displayed_cost) {
         return Vec::new();
     }
-    vec![Span::styled(
+    let mut spans = vec![Span::styled(
         app.format_cost_amount(displayed_cost),
         Style::default().fg(palette::TEXT_MUTED),
-    )]
+    )];
+    // Append cache-savings hint when the last turn had cache hits that
+    // saved money (#2038).
+    if let Some(saved) = app.last_turn_cache_savings()
+        && saved > 0.0
+    {
+        spans.push(Span::styled(
+            format!(" · saved {}", app.format_cost_amount(saved)),
+            Style::default().fg(palette::STATUS_SUCCESS),
+        ));
+    }
+    spans
 }
 
 pub(crate) fn should_show_footer_cost(displayed_cost: f64) -> bool {
     displayed_cost.is_finite() && displayed_cost > 0.0
 }
 
+/// Session token-usage chip for the footer right cluster.
+///
+/// Renders the accumulated input / cache-hit / output token breakdown
+/// since the current runtime session started (not persisted across
+/// restarts). Returns empty when no tokens have been recorded yet.
+pub(crate) fn footer_session_tokens_spans(app: &App) -> Vec<Span<'static>> {
+    let session = &app.session;
+    if session.total_input_tokens == 0 && session.total_output_tokens == 0 {
+        return Vec::new();
+    }
+    let in_str = format_token_count_compact(u64::from(session.total_input_tokens));
+    let out_str = format_token_count_compact(u64::from(session.total_output_tokens));
+    let text = if session.total_cache_hit_tokens == 0 && session.total_cache_miss_tokens == 0 {
+        format!("{in_str} in · {out_str} out")
+    } else {
+        let cache_str = format_token_count_compact(u64::from(session.total_cache_hit_tokens));
+        format!("{in_str} in · {cache_str} cch · {out_str} out")
+    };
+    vec![Span::styled(text, Style::default().fg(palette::TEXT_MUTED))]
+}
+
 /// Test-only helper retained as a parity reference for `FooterWidget`'s
 /// auxiliary-span composition. Production rendering is performed by the
 /// widget itself; the existing footer parity tests still exercise this
@@ -620,6 +639,8 @@ pub(crate) fn footer_auxiliary_spans(app: &App, max_width: usize) -> Vec<Span<'s
         })
         .unwrap_or_default();
 
+    let shell_spans = crate::tui::widgets::footer_shell_chip(active_foreground_shell_running(app));
+
     let parts: Vec<&Vec<Span<'static>>> = [
         &coherence_spans,
         &agents_spans,
@@ -627,6 +648,7 @@ pub(crate) fn footer_auxiliary_spans(app: &App, max_width: usize) -> Vec<Span<'s
         &prefix_spans,
         &cache_spans,
         &cost_spans,
+        &shell_spans,
     ]
     .iter()
     .filter(|spans| !spans.is_empty())
@@ -793,6 +815,9 @@ pub(crate) fn footer_state_label(app: &App) -> (&'static str, ratatui::style::Co
     if app.is_compacting {
         return ("compacting \u{238B}", app.ui_theme.status_warning);
     }
+    if app.is_purging {
+        return ("purging \u{238B}", app.ui_theme.status_warning);
+    }
     // Note: we deliberately do NOT show a "thinking" label for `is_loading`.
     // The animated water-spout strip in the footer's spacer is the visual
     // signal that the model is live; "thinking" was misleading because it
diff --git a/crates/tui/src/tui/history.rs b/crates/tui/src/tui/history.rs
index 477eafa0..d2c19c48 100644
--- a/crates/tui/src/tui/history.rs
+++ b/crates/tui/src/tui/history.rs
@@ -15,13 +15,14 @@ use crate::tools::review::ReviewOutput;
 use crate::tui::app::TranscriptSpacing;
 use crate::tui::diff_render;
 use crate::tui::markdown_render;
+use crate::tui::ui_text::CopyLineSeparator;
 
 // === Constants ===
 
 use std::process::Command;
 const TOOL_COMMAND_LINE_LIMIT: usize = 3;
 const TOOL_OUTPUT_LINE_LIMIT: usize = 6;
-const TOOL_TEXT_LIMIT: usize = 180;
+const TOOL_TEXT_LIMIT: usize = 300;
 const TOOL_HEADER_SUMMARY_LIMIT: usize = 56;
 const TOOL_OUTPUT_HEAD_LINES: usize = 2;
 const TOOL_OUTPUT_TAIL_LINES: usize = 2;
@@ -158,6 +159,12 @@ pub struct TranscriptRenderOptions {
     pub spacing: TranscriptSpacing,
 }
 
+pub(crate) struct RenderedTranscriptLine {
+    pub line: Line<'static>,
+    pub copy_prefix_width: usize,
+    pub copy_separator_after: CopyLineSeparator,
+}
+
 impl Default for TranscriptRenderOptions {
     fn default() -> Self {
         Self {
@@ -242,6 +249,21 @@ impl HistoryCell {
         &self,
         width: u16,
         options: TranscriptRenderOptions,
+    ) -> Vec<Line<'static>> {
+        self.lines_with_options_folded(width, options, false)
+    }
+
+    /// Render with an explicit per-cell fold override for thinking cells.
+    ///
+    /// Uses XOR with the `verbose` flag so that pressing Space toggles
+    /// the collapsed state *relative* to the global setting:
+    /// - verbose off (default): thinking is collapsed; Space unfolds it
+    /// - verbose on: thinking is expanded; Space folds it
+    pub fn lines_with_options_folded(
+        &self,
+        width: u16,
+        options: TranscriptRenderOptions,
+        folded: bool,
     ) -> Vec<Line<'static>> {
         match self {
             HistoryCell::Thinking { .. } if !options.show_thinking => Vec::new(),
@@ -254,7 +276,7 @@ impl HistoryCell {
                 width,
                 *streaming,
                 *duration_secs,
-                !options.verbose,
+                folded ^ !options.verbose,
                 options.low_motion,
             ),
             HistoryCell::Tool(cell) if !options.show_tool_details => {
@@ -296,6 +318,45 @@ impl HistoryCell {
         }
     }
 
+    #[allow(dead_code)]
+    pub(crate) fn lines_with_copy_metadata(
+        &self,
+        width: u16,
+        options: TranscriptRenderOptions,
+    ) -> Vec<RenderedTranscriptLine> {
+        self.lines_with_copy_metadata_folded(width, options, false)
+    }
+
+    pub(crate) fn lines_with_copy_metadata_folded(
+        &self,
+        width: u16,
+        options: TranscriptRenderOptions,
+        folded: bool,
+    ) -> Vec<RenderedTranscriptLine> {
+        match self {
+            HistoryCell::User { content } => {
+                hard_break_copy_lines(render_user_message(content, width))
+            }
+            HistoryCell::Assistant { content, streaming } => render_message_with_copy_metadata(
+                ASSISTANT_GLYPH,
+                assistant_label_style_for(*streaming, options.low_motion),
+                message_body_style(),
+                content,
+                width,
+            ),
+            HistoryCell::System { content } if !is_cycle_boundary(content) => {
+                render_message_with_copy_metadata(
+                    "Note",
+                    system_label_style(),
+                    system_body_style(),
+                    content,
+                    width,
+                )
+            }
+            _ => hard_break_copy_lines(self.lines_with_options_folded(width, options, folded)),
+        }
+    }
+
     /// Render the cell in transcript mode: full content, no caps, no
     /// "Alt+V for details" affordances.
     ///
@@ -2175,7 +2236,7 @@ fn render_thinking(
         let label = if streaming {
             "More reasoning in Ctrl+O"
         } else {
-            "Full reasoning in Ctrl+O"
+            "Space to expand · Full reasoning in Ctrl+O"
         };
         lines.push(Line::from(vec![
             Span::styled(REASONING_RAIL.to_string(), rail_style),
@@ -2193,6 +2254,19 @@ fn render_message(
     content: &str,
     width: u16,
 ) -> Vec<Line<'static>> {
+    render_message_with_copy_metadata(prefix, label_style, body_style, content, width)
+        .into_iter()
+        .map(|rendered| rendered.line)
+        .collect()
+}
+
+fn render_message_with_copy_metadata(
+    prefix: &str,
+    label_style: Style,
+    body_style: Style,
+    content: &str,
+    width: u16,
+) -> Vec<RenderedTranscriptLine> {
     let prefix_width = UnicodeWidthStr::width(prefix);
     let prefix_width_u16 = u16::try_from(prefix_width.saturating_add(2)).unwrap_or(u16::MAX);
     let content_width = usize::from(width.saturating_sub(prefix_width_u16).max(1));
@@ -2200,7 +2274,7 @@ fn render_message(
     let rendered =
         markdown_render::render_markdown_tagged(content, content_width as u16, body_style);
     for (idx, rendered_line) in rendered.into_iter().enumerate() {
-        if idx == 0 {
+        let line = if idx == 0 {
             let mut spans = Vec::new();
             if !prefix.is_empty() {
                 spans.push(Span::styled(
@@ -2210,7 +2284,7 @@ fn render_message(
                 spans.push(Span::raw(" "));
             }
             spans.extend(rendered_line.line.spans);
-            lines.push(Line::from(spans));
+            Line::from(spans)
         } else {
             let indent = if prefix.is_empty() {
                 String::new()
@@ -2225,15 +2299,49 @@ fn render_message(
             let rail_style = Style::default().fg(palette::TEXT_DIM);
             let mut spans = vec![Span::styled(indent, rail_style)];
             spans.extend(rendered_line.line.spans);
-            lines.push(Line::from(spans));
-        }
+            Line::from(spans)
+        };
+        lines.push(RenderedTranscriptLine {
+            line,
+            copy_prefix_width: rendered_line.copy_prefix_width
+                + history_copy_prefix_width(prefix, prefix_width, rendered_line.is_code, idx),
+            copy_separator_after: rendered_line.copy_separator_after,
+        });
     }
     if lines.is_empty() {
-        lines.push(Line::from(""));
+        lines.push(RenderedTranscriptLine {
+            line: Line::from(""),
+            copy_prefix_width: 0,
+            copy_separator_after: CopyLineSeparator::Newline,
+        });
     }
     lines
 }
 
+fn history_copy_prefix_width(
+    prefix: &str,
+    prefix_width: usize,
+    is_code: bool,
+    line_index: usize,
+) -> usize {
+    if line_index > 0 && is_code && !prefix.is_empty() {
+        prefix_width + 1
+    } else {
+        0
+    }
+}
+
+fn hard_break_copy_lines(lines: Vec<Line<'static>>) -> Vec<RenderedTranscriptLine> {
+    lines
+        .into_iter()
+        .map(|line| RenderedTranscriptLine {
+            line,
+            copy_prefix_width: 0,
+            copy_separator_after: CopyLineSeparator::Newline,
+        })
+        .collect()
+}
+
 /// Render a plain-text user message: split on newlines, word-wrap each line,
 /// preserve leading whitespace. No markdown interpretation (headings, lists,
 /// code blocks, etc. are rendered as literal text).
diff --git a/crates/tui/src/tui/key_actions.rs b/crates/tui/src/tui/key_actions.rs
new file mode 100644
index 00000000..ad815031
--- /dev/null
+++ b/crates/tui/src/tui/key_actions.rs
@@ -0,0 +1,56 @@
+//! Keyboard event action handlers extracted from `ui.rs`.
+//!
+//! Each function handles a focused subset of keyboard input so the
+//! main event loop stays lean.
+
+use crossterm::event::{KeyCode, KeyEvent};
+
+use super::app::App;
+
+// ── File-tree key handling ───────────────────────────────────────
+
+/// Handle keyboard input when the file-tree pane is visible.
+///
+/// Returns `true` when the key was consumed (caller should `continue`).
+pub fn handle_file_tree_key(app: &mut App, key: &KeyEvent) -> bool {
+    // Guard: do not intercept keys when the file-tree pane is not visible.
+    if !app.file_tree_visible {
+        return false;
+    }
+
+    // Esc closes the tree even when entries are still loading.
+    if key.code == KeyCode::Esc && app.file_tree.is_some() {
+        app.file_tree = None;
+        app.status_message = Some("File tree closed".to_string());
+        app.needs_redraw = true;
+        return true;
+    }
+
+    let Some(file_tree) = app.file_tree.as_mut() else {
+        return false;
+    };
+
+    match key.code {
+        KeyCode::Up => {
+            file_tree.cursor_up();
+            app.needs_redraw = true;
+            true
+        }
+        KeyCode::Down => {
+            file_tree.cursor_down();
+            app.needs_redraw = true;
+            true
+        }
+        KeyCode::Enter => {
+            if let Some(rel_path) = file_tree.activate() {
+                let path_str = rel_path.to_string_lossy().to_string();
+                app.status_message = Some(format!("Attached @{path_str}"));
+                app.insert_str(&format!("@{path_str} "));
+            } else {
+                app.needs_redraw = true;
+            }
+            true
+        }
+        _ => false,
+    }
+}
diff --git a/crates/tui/src/tui/markdown_render.rs b/crates/tui/src/tui/markdown_render.rs
index 0ad25467..0d645510 100644
--- a/crates/tui/src/tui/markdown_render.rs
+++ b/crates/tui/src/tui/markdown_render.rs
@@ -33,6 +33,7 @@ use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};
 
 use crate::palette;
 use crate::tui::osc8;
+use crate::tui::ui_text::CopyLineSeparator;
 
 // Thread-local counter incremented every time `parse` runs. Used by tests to
 // prove that width-only changes hit the cached-AST path and skip parsing.
@@ -101,6 +102,8 @@ pub struct ParsedMarkdown {
 pub struct RenderedMarkdownLine {
     pub line: Line<'static>,
     pub is_code: bool,
+    pub copy_prefix_width: usize,
+    pub copy_separator_after: CopyLineSeparator,
 }
 
 /// Parse markdown source into a width-independent block AST.
@@ -227,6 +230,8 @@ pub fn render_parsed_tagged(
                     .map(|line| RenderedMarkdownLine {
                         line,
                         is_code: false,
+                        copy_prefix_width: 0,
+                        copy_separator_after: CopyLineSeparator::Newline,
                     }),
             );
             continue;
@@ -246,6 +251,8 @@ pub fn render_parsed_tagged(
                         Style::default().fg(palette::TEXT_DIM),
                     )),
                     is_code: false,
+                    copy_prefix_width: 0,
+                    copy_separator_after: CopyLineSeparator::Newline,
                 });
             }
             Block::HorizontalRule => {
@@ -255,18 +262,19 @@ pub fn render_parsed_tagged(
                         Style::default().fg(palette::TEXT_DIM),
                     )),
                     is_code: false,
+                    copy_prefix_width: 0,
+                    copy_separator_after: CopyLineSeparator::Newline,
                 });
             }
             Block::ListItem { bullet, text } => {
                 let bullet_style = Style::default().fg(palette::DEEPSEEK_SKY);
-                out.extend(
-                    render_list_line(bullet, text, width, bullet_style, base_style)
-                        .into_iter()
-                        .map(|line| RenderedMarkdownLine {
-                            line,
-                            is_code: false,
-                        }),
-                );
+                out.extend(render_list_line_tagged(
+                    bullet,
+                    text,
+                    width,
+                    bullet_style,
+                    base_style,
+                ));
             }
             Block::Code { line } => {
                 let code_style = Style::default()
@@ -280,19 +288,16 @@ pub fn render_parsed_tagged(
                 let link_style = Style::default()
                     .fg(palette::DEEPSEEK_BLUE)
                     .add_modifier(Modifier::UNDERLINED);
-                out.extend(
-                    render_line_with_links(text, width, base_style, link_style)
-                        .into_iter()
-                        .map(|line| RenderedMarkdownLine {
-                            line,
-                            is_code: false,
-                        }),
-                );
+                out.extend(render_line_with_links_tagged(
+                    text, width, base_style, link_style,
+                ));
             }
             Block::Blank => {
                 out.push(RenderedMarkdownLine {
                     line: Line::from(""),
                     is_code: false,
+                    copy_prefix_width: 0,
+                    copy_separator_after: CopyLineSeparator::Newline,
                 });
             }
             Block::TableRow(_) | Block::TableSeparator => unreachable!(),
@@ -304,6 +309,8 @@ pub fn render_parsed_tagged(
         out.push(RenderedMarkdownLine {
             line: Line::from(""),
             is_code: false,
+            copy_prefix_width: 0,
+            copy_separator_after: CopyLineSeparator::Newline,
         });
     }
 
@@ -484,6 +491,7 @@ fn render_wrapped_line_tagged(
     };
     let mut out = Vec::new();
 
+    let last_index = wrapped.len().saturating_sub(1);
     for (idx, chunk) in wrapped.into_iter().enumerate() {
         let line = if idx == 0 {
             Line::from(vec![Span::raw(prefix), Span::styled(chunk, style)])
@@ -493,47 +501,87 @@ fn render_wrapped_line_tagged(
                 Span::styled(chunk, style),
             ])
         };
-        out.push(RenderedMarkdownLine { line, is_code });
+        let copy_separator_after = if idx == last_index {
+            CopyLineSeparator::Newline
+        } else if is_code {
+            CopyLineSeparator::None
+        } else {
+            CopyLineSeparator::Space
+        };
+        out.push(RenderedMarkdownLine {
+            line,
+            is_code,
+            copy_prefix_width: if indent_code { prefix_width } else { 0 },
+            copy_separator_after,
+        });
     }
 
     out
 }
 
-fn render_list_line(
+fn render_list_line_tagged(
     bullet: &str,
     text: &str,
     width: usize,
     bullet_style: Style,
     text_style: Style,
-) -> Vec<Line<'static>> {
+) -> Vec<RenderedMarkdownLine> {
     let bullet_prefix = format!("{bullet} ");
     let bullet_width = bullet_prefix.width();
     let available = width.saturating_sub(bullet_width).max(1);
-    let wrapped = render_line_with_links(text, available, text_style, link_style());
+    let wrapped = render_line_with_links_tagged(text, available, text_style, link_style());
 
     let mut out = Vec::new();
-    for (idx, line) in wrapped.into_iter().enumerate() {
+    for (idx, rendered) in wrapped.into_iter().enumerate() {
         if idx == 0 {
             let mut spans = vec![Span::styled(bullet_prefix.clone(), bullet_style)];
-            spans.extend(line.spans);
-            out.push(Line::from(spans));
+            spans.extend(rendered.line.spans);
+            out.push(RenderedMarkdownLine {
+                line: Line::from(spans),
+                is_code: false,
+                copy_prefix_width: 0,
+                copy_separator_after: rendered.copy_separator_after,
+            });
         } else {
             let mut spans = vec![Span::raw(" ".repeat(bullet_width))];
-            spans.extend(line.spans);
-            out.push(Line::from(spans));
+            spans.extend(rendered.line.spans);
+            out.push(RenderedMarkdownLine {
+                line: Line::from(spans),
+                is_code: false,
+                copy_prefix_width: bullet_width,
+                copy_separator_after: rendered.copy_separator_after,
+            });
         }
     }
     out
 }
 
+#[cfg(test)]
 fn render_line_with_links(
     line: &str,
     width: usize,
     base_style: Style,
     link_style: Style,
 ) -> Vec<Line<'static>> {
+    render_line_with_links_tagged(line, width, base_style, link_style)
+        .into_iter()
+        .map(|rendered| rendered.line)
+        .collect()
+}
+
+fn render_line_with_links_tagged(
+    line: &str,
+    width: usize,
+    base_style: Style,
+    link_style: Style,
+) -> Vec<RenderedMarkdownLine> {
     if line.trim().is_empty() {
-        return vec![Line::from("")];
+        return vec![RenderedMarkdownLine {
+            line: Line::from(""),
+            is_code: false,
+            copy_prefix_width: 0,
+            copy_separator_after: CopyLineSeparator::Newline,
+        }];
     }
 
     // Flatten inline tokens into (word, style) pairs preserving inter-token spaces.
@@ -558,8 +606,8 @@ fn render_line_with_links(
         }
     }
 
-    let mut lines = Vec::new();
-    let mut current_spans: Vec<Span> = Vec::new();
+    let mut lines: Vec<RenderedMarkdownLine> = Vec::new();
+    let mut current_spans: Vec<Span<'static>> = Vec::new();
     let mut current_width = 0usize;
 
     for word in words {
@@ -581,12 +629,7 @@ fn render_line_with_links(
         if ww > width && width > 0 {
             // Flush the in-progress line first.
             if !current_spans.is_empty() {
-                if let Some(last) = current_spans.last()
-                    && last.content.as_ref() == " "
-                {
-                    current_spans.pop();
-                }
-                lines.push(Line::from(std::mem::take(&mut current_spans)));
+                push_inline_line(&mut lines, &mut current_spans, CopyLineSeparator::Space);
                 current_width = 0;
             }
             // Char-break the word into width-sized chunks. Each full chunk
@@ -597,7 +640,12 @@ fn render_line_with_links(
             for ch in word.text.chars() {
                 let cw = ch.width().unwrap_or(1);
                 if chunk_w + cw > width && chunk_w > 0 {
-                    lines.push(Line::from(vec![word.span_for(std::mem::take(&mut chunk))]));
+                    lines.push(RenderedMarkdownLine {
+                        line: Line::from(vec![word.span_for(std::mem::take(&mut chunk))]),
+                        is_code: false,
+                        copy_prefix_width: 0,
+                        copy_separator_after: CopyLineSeparator::None,
+                    });
                     chunk_w = 0;
                 }
                 chunk.push(ch);
@@ -612,13 +660,7 @@ fn render_line_with_links(
         // Wrap before this word if it doesn't fit.
         if current_width > 0 && current_width + ww > width {
             // Trim trailing space span before breaking.
-            if let Some(last) = current_spans.last()
-                && last.content.as_ref() == " "
-            {
-                current_spans.pop();
-            }
-            lines.push(Line::from(current_spans));
-            current_spans = Vec::new();
+            push_inline_line(&mut lines, &mut current_spans, CopyLineSeparator::Space);
             current_width = 0;
         }
         current_spans.push(word.into_span());
@@ -626,14 +668,39 @@ fn render_line_with_links(
     }
 
     if !current_spans.is_empty() {
-        lines.push(Line::from(current_spans));
+        push_inline_line(&mut lines, &mut current_spans, CopyLineSeparator::Newline);
+    } else if let Some(last) = lines.last_mut() {
+        last.copy_separator_after = CopyLineSeparator::Newline;
     }
     if lines.is_empty() {
-        lines.push(Line::from(""));
+        lines.push(RenderedMarkdownLine {
+            line: Line::from(""),
+            is_code: false,
+            copy_prefix_width: 0,
+            copy_separator_after: CopyLineSeparator::Newline,
+        });
     }
     lines
 }
 
+fn push_inline_line(
+    lines: &mut Vec<RenderedMarkdownLine>,
+    spans: &mut Vec<Span<'static>>,
+    copy_separator_after: CopyLineSeparator,
+) {
+    if let Some(last) = spans.last()
+        && last.content.as_ref() == " "
+    {
+        spans.pop();
+    }
+    lines.push(RenderedMarkdownLine {
+        line: Line::from(std::mem::take(spans)),
+        is_code: false,
+        copy_prefix_width: 0,
+        copy_separator_after,
+    });
+}
+
 #[derive(Clone)]
 struct InlineToken {
     text: String,
@@ -1571,7 +1638,7 @@ mod tests {
     fn table_pipes_inside_inline_code_stay_in_the_cell() {
         let src = "| Check | Result |\n\
                    |---|---|\n\
-                   | `strings ~/.cargo/bin/codewhale-tui | grep -c \"Goal mode\"` | 0 matches |\n";
+                   | `strings ~/.cargo/bin/codewhale-tui | grep -c \"legacy marker\"` | 0 matches |\n";
         let parsed = parse(src);
 
         let rows: Vec<&Vec<String>> = parsed
@@ -1587,7 +1654,7 @@ mod tests {
         assert_eq!(
             rows[1],
             &vec![
-                "`strings ~/.cargo/bin/codewhale-tui | grep -c \"Goal mode\"`".to_string(),
+                "`strings ~/.cargo/bin/codewhale-tui | grep -c \"legacy marker\"`".to_string(),
                 "0 matches".to_string(),
             ]
         );
diff --git a/crates/tui/src/tui/mod.rs b/crates/tui/src/tui/mod.rs
index d36b81cd..af2d8996 100644
--- a/crates/tui/src/tui/mod.rs
+++ b/crates/tui/src/tui/mod.rs
@@ -35,6 +35,7 @@ pub mod footer_ui;
 pub mod format_helpers;
 pub mod frame_rate_limiter;
 pub mod history;
+pub mod key_actions;
 pub mod key_shortcuts;
 pub mod keybindings;
 pub mod live_transcript;
@@ -70,11 +71,11 @@ mod ui_text;
 pub mod user_input;
 pub mod views;
 pub mod vim_mode;
-pub mod voice_input;
+pub mod whale_routes;
 pub mod widgets;
 pub mod workspace_context;
 
 // === Re-exports ===
 
-pub use app::TuiOptions;
+pub use app::{InitialInput, TuiOptions};
 pub use ui::run_tui;
diff --git a/crates/tui/src/tui/model_picker.rs b/crates/tui/src/tui/model_picker.rs
index 88ce4949..105f4bdc 100644
--- a/crates/tui/src/tui/model_picker.rs
+++ b/crates/tui/src/tui/model_picker.rs
@@ -1,21 +1,16 @@
-//! `/model` picker modal: pick a DeepSeek model and a thinking-effort tier
-//! and apply both at once (#39).
+//! `/model` picker modal: pick a model and thinking-effort tier (#39, #2026).
 //!
-//! Two side-by-side panes — Models on the left, Thinking effort on the
-//! right. Tab swaps focus, ↑/↓ moves within the focused pane, Enter applies
-//! both and closes the modal, Esc cancels.
+//! For DeepSeek providers the picker shows whale-sized routes — model + effort
+//! combinations sorted largest → fastest with friendly whale-species labels
+//! (Blue Whale, Fin Whale, …, Beluga).  A single ↑/↓ selection sets both
+//! model and effort at once.  The "auto" option is always available; custom
+//! (unrecognised) model ids appear as a separate row.
 //!
-//! The effort pane intentionally only exposes `Off / High / Max`. Per
-//! DeepSeek's [Thinking Mode docs](https://api-docs.deepseek.com/guides/reasoning_model),
-//! `low`/`medium` are silently mapped to `high` server-side and `xhigh` is
-//! mapped to `max`, so surfacing them as separate choices would be misleading.
-//! The legacy variants remain valid in `~/.deepseek/settings.toml` for
-//! back-compat — the picker just doesn't offer them.
+//! For pass-through providers the picker falls back to the classic two-column
+//! layout (Models | Thinking), with no whale labelling.
 //!
 //! On apply we emit a [`ViewEvent::ModelPickerApplied`] with the resolved
-//! model id and effort tier; the UI handler updates `App` state, persists
-//! the choice via `Settings`, and forwards `Op::SetModel` so the running
-//! engine picks up the change without a restart.
+//! model id and effort tier.
 
 use crossterm::event::{KeyCode, KeyEvent};
 use ratatui::{
@@ -29,6 +24,7 @@ use ratatui::{
 use crate::palette;
 use crate::tui::app::{App, ReasoningEffort};
 use crate::tui::views::{ModalKind, ModalView, ViewAction, ViewEvent};
+use crate::tui::whale_routes::WHALE_ROUTES;
 
 /// Models the picker exposes by default. Kept short on purpose — power
 /// users can still type `/model <id>` for anything else.
@@ -61,18 +57,28 @@ pub struct ModelPickerView {
     selected_model_idx: usize,
     selected_effort_idx: usize,
     focus: Pane,
+    selection_touched: bool,
     /// True when the active model is one we don't list — we still show it
     /// so the picker doesn't quietly forget the user's chosen IDs.
     show_custom_model_row: bool,
     /// When true, hide DeepSeek-specific model rows (pass-through providers
     /// like openai don't support them).
     hide_deepseek_models: bool,
+    /// When true, show whale-sized routes instead of two-column model/effort.
+    show_whale_routes: bool,
+    /// Selected whale-route index (when show_whale_routes is true).
+    selected_route_idx: usize,
 }
 
 impl ModelPickerView {
     #[must_use]
     pub fn new(app: &App) -> Self {
         let hide_deepseek_models = crate::config::provider_passes_model_through(app.api_provider);
+        // Whale routes are DeepSeek-specific — only official providers get them.
+        let show_whale_routes = matches!(
+            app.api_provider,
+            crate::config::ApiProvider::Deepseek | crate::config::ApiProvider::DeepseekCN
+        );
         let initial_model = if app.auto_model {
             "auto".to_string()
         } else {
@@ -102,14 +108,45 @@ impl ModelPickerView {
             .position(|e| *e == normalized)
             .unwrap_or(2); // default to High if somehow unknown
 
+        // When showing whale routes, find the matching route by position in the array
+        // (not by sort_order, which happens to match today but is semantically wrong).
+        let (selected_route_idx, show_custom_model_row) = if show_whale_routes {
+            let idx = WHALE_ROUTES
+                .iter()
+                .position(|r| {
+                    r.model.eq_ignore_ascii_case(&initial_model) && r.effort == normalized
+                })
+                .unwrap_or_else(|| {
+                    // No matching whale route — key the fallback on whether the
+                    // current model is actually "auto", not on show_custom_model_row.
+                    // Otherwise a known DeepSeek model (e.g. v4-pro) paired with
+                    // ReasoningEffort::Auto silently falls through to the "auto" row
+                    // and replaces the explicit model on apply.
+                    if initial_model.eq_ignore_ascii_case("auto") {
+                        WHALE_ROUTES.len() // "auto" row
+                    } else {
+                        WHALE_ROUTES.len() + 1 // custom model row
+                    }
+                });
+            // When the whale-route fallback selected the custom row, ensure it is
+            // visible so the user can see their current model in the picker.
+            let show_custom = show_custom_model_row || idx == WHALE_ROUTES.len() + 1;
+            (idx, show_custom)
+        } else {
+            (0, show_custom_model_row)
+        };
+
         Self {
             initial_model,
             initial_effort,
             selected_model_idx,
             selected_effort_idx,
             focus: Pane::Model,
+            selection_touched: false,
             show_custom_model_row,
             hide_deepseek_models,
+            show_whale_routes,
+            selected_route_idx,
         }
     }
 
@@ -125,10 +162,11 @@ impl ModelPickerView {
         self.visible_model_ids().len() + if self.show_custom_model_row { 1 } else { 0 }
     }
 
-    /// Resolve the currently highlighted model row to a model id. If the
-    /// custom row is selected we return the original model from the App so
-    /// "Apply" doesn't blow away an unrecognised id.
+    /// Resolve the currently highlighted row to a model id.
     fn resolved_model(&self) -> String {
+        if self.show_whale_routes {
+            return self.resolved_whale_model();
+        }
         let visible = self.visible_model_ids();
         if self.show_custom_model_row && self.selected_model_idx == visible.len() {
             self.initial_model.clone()
@@ -140,42 +178,102 @@ impl ModelPickerView {
     }
 
     fn resolved_effort(&self) -> ReasoningEffort {
+        if self.show_whale_routes {
+            return self.resolved_whale_effort();
+        }
         if self.resolved_model().trim().eq_ignore_ascii_case("auto") {
             return ReasoningEffort::Auto;
         }
         PICKER_EFFORTS[self.selected_effort_idx]
     }
 
-    fn move_up(&mut self) {
+    /// Resolve model from the whale-route list.
+    fn resolved_whale_model(&self) -> String {
+        if self.selected_route_idx < WHALE_ROUTES.len() {
+            WHALE_ROUTES[self.selected_route_idx].model.to_string()
+        } else if self.selected_route_idx == WHALE_ROUTES.len() {
+            // First fallback row: always "auto".
+            "auto".to_string()
+        } else {
+            // Second fallback row: custom model.
+            self.initial_model.clone()
+        }
+    }
+
+    /// Resolve effort from the whale-route list.
+    fn resolved_whale_effort(&self) -> ReasoningEffort {
+        if self.selected_route_idx < WHALE_ROUTES.len() {
+            WHALE_ROUTES[self.selected_route_idx].effort
+        } else if self.selected_route_idx == WHALE_ROUTES.len() {
+            // First fallback row: "auto".
+            ReasoningEffort::Auto
+        } else {
+            // Second fallback row: custom model — keep the initial effort.
+            self.initial_effort
+        }
+    }
+
+    /// Number of rows in the whale-route list.
+    fn whale_route_row_count(&self) -> usize {
+        let base = WHALE_ROUTES.len() + 1; // routes + auto
+        if self.show_custom_model_row {
+            base + 1
+        } else {
+            base
+        }
+    }
+
+    fn move_up(&mut self) -> bool {
+        if self.show_whale_routes {
+            if self.selected_route_idx > 0 {
+                self.selected_route_idx -= 1;
+                return true;
+            }
+            return false;
+        }
         match self.focus {
             Pane::Model => {
                 if self.selected_model_idx > 0 {
                     self.selected_model_idx -= 1;
+                    return true;
                 }
             }
             Pane::Effort => {
                 if self.selected_effort_idx > 0 {
                     self.selected_effort_idx -= 1;
+                    return true;
                 }
             }
         }
+        false
     }
 
-    fn move_down(&mut self) {
+    fn move_down(&mut self) -> bool {
+        if self.show_whale_routes {
+            let max = self.whale_route_row_count().saturating_sub(1);
+            if self.selected_route_idx < max {
+                self.selected_route_idx += 1;
+                return true;
+            }
+            return false;
+        }
         match self.focus {
             Pane::Model => {
                 let max = self.model_row_count().saturating_sub(1);
                 if self.selected_model_idx < max {
                     self.selected_model_idx += 1;
+                    return true;
                 }
             }
             Pane::Effort => {
                 let max = PICKER_EFFORTS.len().saturating_sub(1);
                 if self.selected_effort_idx < max {
                     self.selected_effort_idx += 1;
+                    return true;
                 }
             }
         }
+        false
     }
 
     fn toggle_focus(&mut self) {
@@ -265,18 +363,20 @@ impl ModalView for ModelPickerView {
 
     fn handle_key(&mut self, key: KeyEvent) -> ViewAction {
         match key.code {
-            KeyCode::Esc => ViewAction::Close,
+            KeyCode::Esc => ViewAction::EmitAndClose(self.build_event()),
             KeyCode::Enter => ViewAction::EmitAndClose(self.build_event()),
             KeyCode::Up => {
-                self.move_up();
+                self.selection_touched |= self.move_up();
                 ViewAction::None
             }
             KeyCode::Down => {
-                self.move_down();
+                self.selection_touched |= self.move_down();
                 ViewAction::None
             }
             KeyCode::Tab | KeyCode::Right | KeyCode::Left | KeyCode::BackTab => {
-                self.toggle_focus();
+                if !self.show_whale_routes {
+                    self.toggle_focus();
+                }
                 ViewAction::None
             }
             _ => ViewAction::None,
@@ -284,6 +384,88 @@ impl ModalView for ModelPickerView {
     }
 
     fn render(&self, area: Rect, buf: &mut Buffer) {
+        if self.show_whale_routes {
+            self.render_whale_routes(area, buf);
+        } else {
+            self.render_classic(area, buf);
+        }
+    }
+}
+
+impl ModelPickerView {
+    /// Single-column whale-route list for DeepSeek providers.
+    fn render_whale_routes(&self, area: Rect, buf: &mut Buffer) {
+        let popup_width = 62.min(area.width.saturating_sub(4)).max(44);
+        let row_count = self.whale_route_row_count();
+        let popup_height = (row_count as u16 + 4)
+            .min(area.height.saturating_sub(4))
+            .max(8);
+        let popup_area = Rect {
+            x: area.x + (area.width.saturating_sub(popup_width)) / 2,
+            y: area.y + (area.height.saturating_sub(popup_height)) / 2,
+            width: popup_width,
+            height: popup_height,
+        };
+
+        Clear.render(popup_area, buf);
+
+        let outer = Block::default()
+            .title(Line::from(Span::styled(
+                " Whale Routes ",
+                Style::default()
+                    .fg(palette::DEEPSEEK_SKY)
+                    .add_modifier(Modifier::BOLD),
+            )))
+            .title_bottom(Line::from(vec![
+                Span::styled(" ↑↓ ", Style::default().fg(palette::TEXT_MUTED)),
+                Span::raw("choose "),
+                Span::styled(" Enter ", Style::default().fg(palette::TEXT_MUTED)),
+                Span::raw("apply "),
+                Span::styled(" Esc ", Style::default().fg(palette::TEXT_MUTED)),
+                Span::raw("apply "),
+            ]))
+            .borders(Borders::ALL)
+            .border_style(Style::default().fg(palette::BORDER_COLOR))
+            .style(Style::default());
+        let inner = outer.inner(popup_area);
+        outer.render(popup_area, buf);
+
+        let mut rows: Vec<(String, String)> = WHALE_ROUTES
+            .iter()
+            .map(|r| {
+                (
+                    format!("{}  —  {}", r.label, r.hint),
+                    r.description.to_string(),
+                )
+            })
+            .collect();
+
+        // Fallback row 1: always "auto".
+        rows.push((
+            "auto  —  select per turn".to_string(),
+            "Let CodeWhale pick the best model each turn".to_string(),
+        ));
+
+        // Fallback row 2: custom model when the current model isn't recognized.
+        if self.show_custom_model_row {
+            rows.push((
+                format!("{}  —  custom", self.initial_model),
+                "Current model (not a standard route)".to_string(),
+            ));
+        }
+
+        self.render_pane(
+            inner,
+            buf,
+            "Model & thinking",
+            rows,
+            self.selected_route_idx,
+            true,
+        );
+    }
+
+    /// Classic two-column layout for pass-through providers.
+    fn render_classic(&self, area: Rect, buf: &mut Buffer) {
         let popup_width = 64.min(area.width.saturating_sub(4)).max(40);
         let popup_height = 14.min(area.height.saturating_sub(4)).max(10);
         let popup_area = Rect {
@@ -311,7 +493,7 @@ impl ModalView for ModelPickerView {
                 Span::styled(" Enter ", Style::default().fg(palette::TEXT_MUTED)),
                 Span::raw("apply "),
                 Span::styled(" Esc ", Style::default().fg(palette::TEXT_MUTED)),
-                Span::raw("cancel "),
+                Span::raw("apply "),
             ]))
             .borders(Borders::ALL)
             .border_style(Style::default().fg(palette::BORDER_COLOR))
@@ -446,12 +628,7 @@ mod tests {
         app.auto_model = true;
         app.reasoning_effort = ReasoningEffort::Off;
 
-        let mut view = ModelPickerView::new(&app);
-        view.selected_model_idx = 0;
-        view.selected_effort_idx = PICKER_EFFORTS
-            .iter()
-            .position(|effort| *effort == ReasoningEffort::Max)
-            .expect("max effort row");
+        let view = ModelPickerView::new(&app);
 
         assert_eq!(view.resolved_model(), "auto");
         assert_eq!(view.resolved_effort(), ReasoningEffort::Auto);
@@ -496,53 +673,46 @@ mod tests {
     }
 
     #[test]
-    fn arrow_keys_move_within_focused_pane() {
+    fn arrow_keys_move_within_whale_routes() {
         let (app, _lock) = create_test_app();
         let mut view = ModelPickerView::new(&app);
-        // Default focus is Model; move down then up.
-        let initial = view.selected_model_idx;
+        assert!(view.show_whale_routes);
+        let initial = view.selected_route_idx;
         view.handle_key(KeyEvent::new(
             KeyCode::Down,
             crossterm::event::KeyModifiers::NONE,
         ));
-        assert_eq!(view.selected_model_idx, initial + 1);
+        assert_eq!(view.selected_route_idx, initial + 1);
         view.handle_key(KeyEvent::new(
             KeyCode::Up,
             crossterm::event::KeyModifiers::NONE,
         ));
-        assert_eq!(view.selected_model_idx, initial);
+        assert_eq!(view.selected_route_idx, initial);
     }
 
     #[test]
-    fn tab_switches_focus_and_arrow_now_moves_effort() {
-        let (mut app, _lock) = create_test_app();
-        // Default is Max; pin to Off so the Down arrow has
-        // somewhere to go.
-        app.reasoning_effort = ReasoningEffort::Off;
+    fn tab_is_noop_in_whale_route_mode() {
+        let (app, _lock) = create_test_app();
         let mut view = ModelPickerView::new(&app);
-        let initial_effort_idx = view.selected_effort_idx;
+        assert!(view.show_whale_routes);
+        let before = view.selected_route_idx;
         view.handle_key(KeyEvent::new(
             KeyCode::Tab,
             crossterm::event::KeyModifiers::NONE,
         ));
-        assert_eq!(view.focus, Pane::Effort);
-        view.handle_key(KeyEvent::new(
-            KeyCode::Down,
-            crossterm::event::KeyModifiers::NONE,
-        ));
-        assert!(view.selected_effort_idx > initial_effort_idx);
+        assert_eq!(view.selected_route_idx, before);
     }
 
     #[test]
-    fn enter_emits_apply_event_with_selection() {
+    fn enter_with_whale_routes_emits_apply_event() {
         let (mut app, _lock) = create_test_app();
         app.reasoning_effort = ReasoningEffort::High;
+        app.model = "deepseek-v4-pro".to_string();
         app.auto_model = false;
         let mut view = ModelPickerView::new(&app);
-        view.handle_key(KeyEvent::new(
-            KeyCode::Tab,
-            crossterm::event::KeyModifiers::NONE,
-        ));
+        // Initial route: Fin Whale (Pro + High, sort_order=1)
+        assert_eq!(view.selected_route_idx, 1);
+        // Move down to Sperm Whale (Pro + Off, sort_order=2)
         view.handle_key(KeyEvent::new(
             KeyCode::Down,
             crossterm::event::KeyModifiers::NONE,
@@ -559,7 +729,7 @@ mod tests {
                 ..
             }) => {
                 assert_eq!(model, "deepseek-v4-pro");
-                assert_eq!(effort, ReasoningEffort::Max);
+                assert_eq!(effort, ReasoningEffort::Off);
                 assert_eq!(previous_effort, ReasoningEffort::High);
             }
             other => panic!("expected ModelPickerApplied EmitAndClose, got {other:?}"),
@@ -567,14 +737,129 @@ mod tests {
     }
 
     #[test]
-    fn esc_closes_without_emitting() {
+    fn whale_routes_initial_selection_matches_app_state() {
+        let (mut app, _lock) = create_test_app();
+        app.model = "deepseek-v4-flash".to_string();
+        app.auto_model = false;
+        app.reasoning_effort = ReasoningEffort::Max;
+        let view = ModelPickerView::new(&app);
+        // Humpback = Flash + Max, sort_order = 3
+        assert_eq!(view.selected_route_idx, 3);
+        assert_eq!(view.resolved_model(), "deepseek-v4-flash");
+        assert_eq!(view.resolved_effort(), ReasoningEffort::Max);
+    }
+
+    #[test]
+    fn whale_routes_known_model_auto_effort_does_not_fall_to_auto() {
+        // Regression: a known DeepSeek model paired with ReasoningEffort::Auto
+        // must NOT fall through to the "auto" row — that would silently replace
+        // the explicit model with "auto" on apply.
+        let (mut app, _lock) = create_test_app();
+        app.model = "deepseek-v4-pro".to_string();
+        app.auto_model = false;
+        app.reasoning_effort = ReasoningEffort::Auto;
+        let view = ModelPickerView::new(&app);
+        // Should fall to custom row (WHALE_ROUTES.len() + 1), not auto row.
+        assert_eq!(view.selected_route_idx, WHALE_ROUTES.len() + 1);
+        assert_eq!(view.resolved_model(), "deepseek-v4-pro");
+        assert_eq!(view.resolved_effort(), ReasoningEffort::Auto);
+        // The custom row must be visible so the user sees their current model.
+        assert!(view.show_custom_model_row);
+    }
+
+    #[test]
+    fn whale_routes_auto_effort_maps_to_fallback_row() {
+        let (mut app, _lock) = create_test_app();
+        app.model = "auto".to_string();
+        app.auto_model = true;
+        app.reasoning_effort = ReasoningEffort::Auto;
+        let view = ModelPickerView::new(&app);
+        // "auto" doesn't match any whale route, falls to fallback row
+        assert_eq!(view.selected_route_idx, WHALE_ROUTES.len());
+        assert_eq!(view.resolved_model(), "auto");
+        assert_eq!(view.resolved_effort(), ReasoningEffort::Auto);
+    }
+
+    #[test]
+    fn whale_routes_custom_model_falls_back() {
+        let (mut app, _lock) = create_test_app();
+        app.model = "deepseek-v4-pro-2026-04-XX".to_string();
+        app.auto_model = false;
+        app.reasoning_effort = ReasoningEffort::High;
+        let view = ModelPickerView::new(&app);
+        // Custom model → second fallback row (after "auto")
+        assert_eq!(view.selected_route_idx, WHALE_ROUTES.len() + 1);
+        assert_eq!(view.resolved_model(), "deepseek-v4-pro-2026-04-XX");
+        assert_eq!(view.resolved_effort(), ReasoningEffort::High);
+        // Row count includes routes + auto + custom
+        assert_eq!(view.whale_route_row_count(), WHALE_ROUTES.len() + 2);
+    }
+
+    #[test]
+    fn whale_routes_down_from_last_is_noop() {
+        let (app, _lock) = create_test_app();
+        let mut view = ModelPickerView::new(&app);
+        // Navigate to the last row
+        view.selected_route_idx = view.whale_route_row_count() - 1;
+        let result = view.move_down();
+        assert!(!result);
+    }
+
+    #[test]
+    fn whale_routes_up_from_first_is_noop() {
+        let (app, _lock) = create_test_app();
+        let mut view = ModelPickerView::new(&app);
+        view.selected_route_idx = 0;
+        let result = view.move_up();
+        assert!(!result);
+    }
+
+    #[test]
+    fn immediate_esc_applies_current_selection() {
         let (app, _lock) = create_test_app();
         let mut view = ModelPickerView::new(&app);
         let action = view.handle_key(KeyEvent::new(
             KeyCode::Esc,
             crossterm::event::KeyModifiers::NONE,
         ));
-        assert!(matches!(action, ViewAction::Close));
+        match action {
+            ViewAction::EmitAndClose(ViewEvent::ModelPickerApplied { model, .. }) => {
+                assert_eq!(model, "deepseek-v4-pro");
+            }
+            other => panic!("expected Esc to apply current selection, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn esc_after_selection_move_applies_highlighted_route() {
+        let (mut app, _lock) = create_test_app();
+        app.reasoning_effort = ReasoningEffort::High;
+        let mut view = ModelPickerView::new(&app);
+        // Initial: Fin Whale (Pro+High), previous_effort=High
+        // Down → Sperm Whale (Pro+Off)
+        view.handle_key(KeyEvent::new(
+            KeyCode::Down,
+            crossterm::event::KeyModifiers::NONE,
+        ));
+
+        let action = view.handle_key(KeyEvent::new(
+            KeyCode::Esc,
+            crossterm::event::KeyModifiers::NONE,
+        ));
+
+        match action {
+            ViewAction::EmitAndClose(ViewEvent::ModelPickerApplied {
+                model,
+                effort,
+                previous_effort,
+                ..
+            }) => {
+                assert_eq!(model, "deepseek-v4-pro");
+                assert_eq!(effort, ReasoningEffort::Off);
+                assert_eq!(previous_effort, ReasoningEffort::High);
+            }
+            other => panic!("expected Esc to apply highlighted route, got {other:?}"),
+        }
     }
 
     #[test]
diff --git a/crates/tui/src/tui/mouse_ui.rs b/crates/tui/src/tui/mouse_ui.rs
index 589c31ae..8d742b87 100644
--- a/crates/tui/src/tui/mouse_ui.rs
+++ b/crates/tui/src/tui/mouse_ui.rs
@@ -2,7 +2,10 @@ use std::time::{Duration, Instant};
 
 use crossterm::event::{MouseButton, MouseEvent, MouseEventKind};
 use ratatui::layout::Rect;
+use unicode_segmentation::UnicodeSegmentation;
+use unicode_width::UnicodeWidthStr;
 
+use crate::localization::MessageId;
 use crate::tui::app::App;
 use crate::tui::command_palette::{
     CommandPaletteView, build_entries as build_command_palette_entries,
@@ -37,6 +40,91 @@ pub(crate) fn should_drop_loading_mouse_motion(app: &App, mouse: MouseEvent) ->
     }
 }
 
+/// Map a mouse (column, row) within the composer area to a char index
+/// in the composer input string. Uses the inner content rect (border-aware)
+/// for coordinate mapping, and accounts for vertical padding and scroll offset.
+fn mouse_pos_to_char_index(app: &App, col: u16, row: u16, inner: Rect) -> Option<usize> {
+    let rel_col = col.saturating_sub(inner.x) as usize;
+    let rel_row = row.saturating_sub(inner.y) as usize;
+
+    if app.input.is_empty() {
+        return Some(0);
+    }
+
+    let width = inner.width.max(1) as usize;
+    let wrapped = crate::tui::widgets::wrap_input_lines_for_mouse(&app.input, width);
+
+    // Subtract the vertical top-padding (centering of short inputs).
+    let text_row = rel_row.saturating_sub(app.viewport.last_composer_top_padding);
+
+    // Add the scroll offset (lines scrolled out of view).
+    let absolute_row = text_row + app.viewport.last_composer_scroll_offset;
+
+    if absolute_row >= wrapped.len() {
+        return Some(app.input.chars().count());
+    }
+
+    let (line_start, line_text) = &wrapped[absolute_row];
+
+    let mut char_offset = 0usize;
+    let mut col_used = 0usize;
+    for g in line_text.graphemes(true) {
+        let gw = g.width();
+        if col_used + gw > rel_col {
+            break;
+        }
+        col_used += gw;
+        char_offset += g.chars().count();
+    }
+    Some(line_start + char_offset)
+}
+
+/// Handle mouse events within the composer area.
+/// Returns true if the event was consumed.
+pub(crate) fn handle_composer_mouse(app: &mut App, mouse: MouseEvent) -> bool {
+    // Use outer area for hit-testing (includes border).
+    let Some(area) = app.viewport.last_composer_area else {
+        return false;
+    };
+    if mouse.column < area.x
+        || mouse.column >= area.x + area.width
+        || mouse.row < area.y
+        || mouse.row >= area.y + area.height
+    {
+        return false;
+    }
+    // Use inner content rect for coordinate-to-char mapping (border-aware).
+    let inner = app.viewport.last_composer_content.unwrap_or(area);
+
+    match mouse.kind {
+        MouseEventKind::Down(MouseButton::Left) => {
+            if let Some(pos) = mouse_pos_to_char_index(app, mouse.column, mouse.row, inner) {
+                app.cursor_position = pos;
+                app.selection_anchor = None;
+                app.needs_redraw = true;
+            }
+            true
+        }
+        MouseEventKind::Drag(MouseButton::Left) => {
+            if let Some(pos) = mouse_pos_to_char_index(app, mouse.column, mouse.row, inner) {
+                if app.selection_anchor.is_none() {
+                    app.selection_anchor = Some(app.cursor_position);
+                }
+                app.cursor_position = pos;
+                app.needs_redraw = true;
+            }
+            true
+        }
+        MouseEventKind::Up(MouseButton::Left) => {
+            if app.selection_anchor == Some(app.cursor_position) {
+                app.selection_anchor = None;
+            }
+            true
+        }
+        _ => false,
+    }
+}
+
 pub(crate) fn handle_mouse_event(app: &mut App, mouse: MouseEvent) -> Vec<ViewEvent> {
     if app.view_stack.top_kind() == Some(ModalKind::ContextMenu) {
         if matches!(mouse.kind, MouseEventKind::Down(MouseButton::Right)) {
@@ -52,7 +140,49 @@ pub(crate) fn handle_mouse_event(app: &mut App, mouse: MouseEvent) -> Vec<ViewEv
         return app.view_stack.handle_mouse(mouse);
     }
 
+    // Composer mouse events take priority over transcript.
+    if handle_composer_mouse(app, mouse) {
+        return Vec::new();
+    }
+
     match mouse.kind {
+        MouseEventKind::Moved => {
+            // Update last mouse position for tooltip rendering.
+            app.last_mouse_pos = Some((mouse.column, mouse.row));
+
+            // Check sidebar sections for hover tooltip.
+            let mut found = false;
+            for section in &app.sidebar_hover.sections {
+                if mouse.column >= section.content_area.x
+                    && mouse.column
+                        < section
+                            .content_area
+                            .x
+                            .saturating_add(section.content_area.width)
+                    && mouse.row >= section.content_area.y
+                    && mouse.row
+                        < section
+                            .content_area
+                            .y
+                            .saturating_add(section.content_area.height)
+                {
+                    let line_idx = (mouse.row.saturating_sub(section.content_area.y)) as usize;
+                    if line_idx < section.lines.len() {
+                        let new_tooltip = section.lines[line_idx].clone();
+                        if app.sidebar_hover_tooltip.as_deref() != Some(&new_tooltip) {
+                            app.sidebar_hover_tooltip = Some(new_tooltip);
+                            app.needs_redraw = true;
+                        }
+                        found = true;
+                        break;
+                    }
+                }
+            }
+            if !found && app.sidebar_hover_tooltip.is_some() {
+                app.sidebar_hover_tooltip = None;
+                app.needs_redraw = true;
+            }
+        }
         MouseEventKind::ScrollUp => {
             let update = app.viewport.mouse_scroll.on_scroll(ScrollDirection::Up);
             app.viewport.pending_scroll_delta = app
@@ -305,8 +435,13 @@ pub(crate) fn open_context_menu(app: &mut App, mouse: MouseEvent) {
     if entries.is_empty() {
         return;
     }
-    app.view_stack
-        .push(ContextMenuView::new(entries, mouse.column, mouse.row));
+    let title = app.tr(MessageId::CtxMenuTitle).to_string();
+    app.view_stack.push(ContextMenuView::new(
+        entries,
+        mouse.column,
+        mouse.row,
+        title,
+    ));
     app.needs_redraw = true;
 }
 
@@ -315,17 +450,17 @@ pub(crate) fn build_context_menu_entries(app: &App, mouse: MouseEvent) -> Vec<Co
 
     if selection_has_content(app) {
         entries.push(ContextMenuEntry {
-            label: "Copy selection".to_string(),
-            description: "write selected transcript text".to_string(),
+            label: app.tr(MessageId::CtxMenuCopySelection).to_string(),
+            description: app.tr(MessageId::CtxMenuCopySelectionDesc).to_string(),
             action: ContextMenuAction::CopySelection,
         });
         entries.push(ContextMenuEntry {
-            label: "Open selection".to_string(),
-            description: "show selected text in pager".to_string(),
+            label: app.tr(MessageId::CtxMenuOpenSelection).to_string(),
+            description: app.tr(MessageId::CtxMenuOpenSelectionDesc).to_string(),
             action: ContextMenuAction::OpenSelection,
         });
         entries.push(ContextMenuEntry {
-            label: "Clear selection".to_string(),
+            label: app.tr(MessageId::CtxMenuClearSelection).to_string(),
             description: String::new(),
             action: ContextMenuAction::ClearSelection,
         });
@@ -345,31 +480,31 @@ pub(crate) fn build_context_menu_entries(app: &App, mouse: MouseEvent) -> Vec<Co
             .map(|label| truncate_line_to_width(label.as_str(), 28))
             .unwrap_or_else(|| "message".to_string());
         entries.push(ContextMenuEntry {
-            label: "Open details".to_string(),
+            label: app.tr(MessageId::CtxMenuOpenDetails).to_string(),
             description: target,
             action: ContextMenuAction::OpenDetails { cell_index },
         });
         entries.push(ContextMenuEntry {
-            label: "Copy message".to_string(),
-            description: "write clicked transcript cell".to_string(),
+            label: app.tr(MessageId::CtxMenuCopyMessage).to_string(),
+            description: app.tr(MessageId::CtxMenuCopyMessageDesc).to_string(),
             action: ContextMenuAction::CopyCell { cell_index },
         });
         entries.push(ContextMenuEntry {
-            label: "Open in editor".to_string(),
-            description: "open file:line in $EDITOR".to_string(),
+            label: app.tr(MessageId::CtxMenuOpenInEditor).to_string(),
+            description: app.tr(MessageId::CtxMenuOpenInEditorDesc).to_string(),
             action: ContextMenuAction::OpenFileAtLine { cell_index },
         });
         // Hide/show cell toggle.
         if app.collapsed_cells.contains(&cell_index) {
             entries.push(ContextMenuEntry {
-                label: "Show cell".to_string(),
-                description: "unhide this transcript cell".to_string(),
+                label: app.tr(MessageId::CtxMenuShowCell).to_string(),
+                description: app.tr(MessageId::CtxMenuShowCellDesc).to_string(),
                 action: ContextMenuAction::ShowCell { cell_index },
             });
         } else {
             entries.push(ContextMenuEntry {
-                label: "Hide cell".to_string(),
-                description: "collapse this transcript cell".to_string(),
+                label: app.tr(MessageId::CtxMenuHideCell).to_string(),
+                description: app.tr(MessageId::CtxMenuHideCellDesc).to_string(),
                 action: ContextMenuAction::HideCell { cell_index },
             });
         }
@@ -378,31 +513,32 @@ pub(crate) fn build_context_menu_entries(app: &App, mouse: MouseEvent) -> Vec<Co
     // When cells are hidden, offer a way to show them all.
     if !app.collapsed_cells.is_empty() {
         let count = app.collapsed_cells.len();
+        let label = app.tr(MessageId::CtxMenuShowHidden).to_string();
         entries.push(ContextMenuEntry {
-            label: format!("Show hidden ({count})"),
-            description: "unhide all collapsed cells".to_string(),
+            label: format!("{label} ({count})"),
+            description: app.tr(MessageId::CtxMenuShowHiddenDesc).to_string(),
             action: ContextMenuAction::ShowAllHidden,
         });
     }
 
     entries.push(ContextMenuEntry {
-        label: "Paste".to_string(),
-        description: "insert clipboard into composer".to_string(),
+        label: app.tr(MessageId::CtxMenuPaste).to_string(),
+        description: app.tr(MessageId::CtxMenuPasteDesc).to_string(),
         action: ContextMenuAction::Paste,
     });
     entries.push(ContextMenuEntry {
-        label: "Command palette".to_string(),
-        description: "commands, skills, and tools".to_string(),
+        label: app.tr(MessageId::CtxMenuCmdPalette).to_string(),
+        description: app.tr(MessageId::CtxMenuCmdPaletteDesc).to_string(),
         action: ContextMenuAction::OpenCommandPalette,
     });
     entries.push(ContextMenuEntry {
-        label: "Context inspector".to_string(),
-        description: "active context and cache hints".to_string(),
+        label: app.tr(MessageId::CtxMenuContextInspector).to_string(),
+        description: app.tr(MessageId::CtxMenuContextInspectorDesc).to_string(),
         action: ContextMenuAction::OpenContextInspector,
     });
     entries.push(ContextMenuEntry {
-        label: "Help".to_string(),
-        description: "keybindings and commands".to_string(),
+        label: app.tr(MessageId::CtxMenuHelp).to_string(),
+        description: app.tr(MessageId::CtxMenuHelpDesc).to_string(),
         action: ContextMenuAction::OpenHelp,
     });
 
@@ -548,6 +684,10 @@ pub(crate) fn selection_point_from_position(
 }
 
 pub(crate) fn selection_has_content(app: &App) -> bool {
+    // Composer selection takes priority (same as Cmd+C handler above).
+    if !app.selected_text().is_empty() {
+        return true;
+    }
     selection_to_text(app).is_some_and(|text| !text.is_empty())
 }
 
@@ -576,6 +716,17 @@ pub(crate) fn ctrl_c_disposition(app: &App) -> CtrlCDisposition {
 }
 
 pub(crate) fn copy_active_selection(app: &mut App) {
+    // Composer selection takes priority.
+    let sel = app.selected_text();
+    if !sel.is_empty() {
+        if app.clipboard.write_text(&sel).is_ok() {
+            app.status_message = Some("Selection copied".to_string());
+            app.clear_selection();
+        } else {
+            app.status_message = Some("Copy failed".to_string());
+        }
+        return;
+    }
     if !app.viewport.transcript_selection.is_active() {
         return;
     }
@@ -600,9 +751,14 @@ pub(crate) fn selection_to_text(app: &App) -> Option<String> {
     let end_index = end.line_index.min(lines.len().saturating_sub(1));
     let start_index = start.line_index.min(end_index);
 
-    let mut selected_lines = Vec::new();
+    let line_meta = app.viewport.transcript_cache.line_meta();
+    let mut selected = String::new();
+    let mut separator_before = None;
     #[allow(clippy::needless_range_loop)]
     for line_index in start_index..=end_index {
+        if let Some(separator) = separator_before {
+            selected.push_str(separator);
+        }
         // Rail-prefix decorations are stored as cache metadata rather than
         // detected from glyphs, so new decoration types are covered without
         // changes to the copy path (#1163).
@@ -611,30 +767,50 @@ pub(crate) fn selection_to_text(app: &App) -> Option<String> {
         // slice off the rail prefix so subsequent column offsets operate
         // on content-only text.
         let full_text = line_to_plain(&lines[line_index]);
-        let line_text = if rail_width > 0 {
+        let line_after_rail = if rail_width > 0 {
             slice_text(&full_text, rail_width, text_display_width(&full_text))
         } else {
             full_text
         };
+        let line_after_rail_width = text_display_width(&line_after_rail);
+        let copy_prefix_width = line_meta
+            .get(line_index)
+            .map(|meta| meta.copy_prefix_width())
+            .unwrap_or(0)
+            .min(line_after_rail_width);
+        let line_text = if copy_prefix_width > 0 {
+            slice_text(&line_after_rail, copy_prefix_width, line_after_rail_width)
+        } else {
+            line_after_rail
+        };
         let line_width = text_display_width(&line_text);
+        let visual_prefix_width = rail_width.saturating_add(copy_prefix_width);
         // Selection coordinates are recorded in rendered-column space, which
-        // includes the visual rail prefix. Add rail_width back so the column
-        // window maps correctly into the rail-stripped text.
+        // includes visual prefixes. Add them back so the column window maps
+        // correctly into copy-only text.
         let (raw_col_start, raw_col_end) = if start_index == end_index {
             (start.column, end.column)
         } else if line_index == start_index {
-            (start.column, line_width.saturating_add(rail_width))
+            (start.column, line_width.saturating_add(visual_prefix_width))
         } else if line_index == end_index {
             (0, end.column)
         } else {
-            (0, line_width.saturating_add(rail_width))
+            (0, line_width.saturating_add(visual_prefix_width))
         };
 
-        let col_start = raw_col_start.saturating_sub(rail_width).min(line_width);
-        let col_end = raw_col_end.saturating_sub(rail_width).min(line_width);
+        let col_start = raw_col_start
+            .saturating_sub(visual_prefix_width)
+            .min(line_width);
+        let col_end = raw_col_end
+            .saturating_sub(visual_prefix_width)
+            .min(line_width);
 
         let slice = slice_text(&line_text, col_start, col_end);
-        selected_lines.push(slice);
+        selected.push_str(&slice);
+        separator_before = line_meta
+            .get(line_index)
+            .map(|meta| meta.copy_separator_after().as_str())
+            .or(Some("\n"));
     }
-    Some(selected_lines.join("\n"))
+    Some(selected)
 }
diff --git a/crates/tui/src/tui/notifications.rs b/crates/tui/src/tui/notifications.rs
index 670f73f9..47d08660 100644
--- a/crates/tui/src/tui/notifications.rs
+++ b/crates/tui/src/tui/notifications.rs
@@ -8,8 +8,8 @@
 //! - **BEL** — audible bell (`\x07`) as a last-resort fallback.
 //!
 //! When `method = "auto"`, the resolver picks the best method for the
-//! current terminal; Windows falls back to `Off` to avoid the error chime
-//! (#583).
+//! current terminal; Windows falls back to `Bel`, which is routed through
+//! `MessageBeep(MB_OK)` for an audible default notification sound.
 
 #[cfg(target_os = "windows")]
 use windows::Win32::System::Diagnostics::Debug::MessageBeep;
@@ -17,6 +17,8 @@ use windows::Win32::System::Diagnostics::Debug::MessageBeep;
 use windows::Win32::UI::WindowsAndMessaging::MESSAGEBOX_STYLE;
 
 use std::io::{self, Write};
+use std::sync::atomic::AtomicU8;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
 
 /// Notification delivery method.
@@ -30,6 +32,8 @@ pub enum Method {
     Osc9,
     /// Plain BEL character: `\x07`
     Bel,
+    /// osascript
+    MacOS,
     /// Kitty notification protocol (OSC 99) with ST terminator.
     /// Uses `ESC ] 99 ; params ST` — no audible beep, unlike BEL.
     Kitty,
@@ -66,7 +70,7 @@ fn windows_bell() {
 /// - `$TERM` contains `ghostty` → `Osc9` (cmux etc.)
 /// - `$TERM` contains `kitty` → `Kitty`
 /// - Unix unknown → `Bel`
-/// - Windows unknown → `Off`
+/// - Windows unknown → `Bel`
 #[must_use]
 fn resolve_method() -> Method {
     let term_program = std::env::var("TERM_PROGRAM").unwrap_or_default();
@@ -85,8 +89,17 @@ fn resolve_method() -> Method {
         _ => {}
     }
 
+    // Windows: use BEL so `windows_bell()` (MessageBeep) fires on turn
+    // completion.  Previous behavior returned `Off` to avoid the error chime
+    // (#583), but `MessageBeep(MB_OK)` plays the *default system sound* —
+    // distinct from the error sound — so BEL is safe and gives Windows users
+    // audible feedback when a long turn finishes.
     if cfg!(target_os = "windows") {
-        return Method::Off;
+        return Method::Bel;
+    }
+
+    if cfg!(target_os = "macos") {
+        return Method::MacOS;
     }
 
     // Ghostty-based terminals (cmux, etc.) may not set their own
@@ -146,8 +159,8 @@ fn build_escape(method: Method, in_tmux: bool, msg: &str) -> Vec<u8> {
             let seq = format!("\x1b]777;notify;codewhale;{msg}\x07");
             wrap_for_multiplexer(&seq, in_tmux).into_bytes()
         }
-        // Auto and Off should not reach build_escape.
-        Method::Auto | Method::Off => vec![],
+        // Auto and Off and MacOS should not reach build_escape.
+        Method::Auto | Method::Off | Method::MacOS => vec![],
     }
 }
 
@@ -171,6 +184,14 @@ pub fn notify_done_to<W: Write>(
         Method::Auto => resolve_method(),
         other => other,
     };
+
+    // macOS Notification Center: handled via osascript, not terminal escapes.
+    #[cfg(target_os = "macos")]
+    if Method::MacOS == effective {
+        macos_display_notification(msg);
+        return;
+    }
+
     let bytes = build_escape(effective, in_tmux, msg);
     if bytes.is_empty() {
         return;
@@ -192,8 +213,8 @@ pub fn notify_done_to<W: Write>(
 ///
 /// With `method = Auto`, selects the best protocol for the current terminal
 /// (OSC 9, Kitty OSC 99, Ghostty OSC 777, or Bel). The unknown-terminal
-/// fallback is platform-aware — `Bel` on macOS / Linux, `Off` on Windows
-/// (where BEL maps to the `SystemAsterisk` / `MB_OK` error chime, #583).
+/// fallback is platform-aware: `Bel` on every platform, with Windows routing
+/// it through `MessageBeep(MB_OK)` for a default system notification sound.
 /// See [`resolve_method`] for the canonical resolution table. Pass
 /// `in_tmux = true` (i.e. `$TMUX` is non-empty at runtime) to wrap OSC
 /// sequences in a DCS passthrough.
@@ -207,6 +228,270 @@ pub fn notify_done(
     notify_done_to(method, in_tmux, msg, threshold, elapsed, &mut io::stdout());
 }
 
+/// Set the terminal taskbar progress state via OSC 9 ; 4.
+///
+/// Windows Terminal supports this to show progress on the taskbar icon:
+/// - `state = 0` — no progress (clear)
+/// - `state = 1` — indeterminate (cycling green)
+/// - `state = 2` — normal (0-100, requires progress param)
+/// - `state = 3` — error (red)
+/// - `state = 4` — paused (yellow)
+///
+/// Other terminals (iTerm2, WezTerm) ignore the sequence silently.
+/// Best-effort — write failures are ignored.
+pub fn set_taskbar_progress(state: u8, progress: Option<u8>) {
+    let seq = if let Some(pct) = progress {
+        format!("\x1b]9;4;{state};{pct}\x07")
+    } else {
+        format!("\x1b]9;4;{state}\x07")
+    };
+    let mut stdout = io::stdout();
+    let _ = stdout.write_all(seq.as_bytes());
+    let _ = stdout.flush();
+}
+
+/// Set taskbar progress to indeterminate (cycling) — call at turn start.
+pub fn set_taskbar_progress_busy() {
+    set_taskbar_progress(1, None);
+}
+
+/// Clear taskbar progress — call at turn end.
+pub fn clear_taskbar_progress() {
+    set_taskbar_progress(0, None);
+}
+
+/// Animation frame characters for the terminal title.
+/// Uses the DeepSeek whale emoji (🐳 spouting, 🐋 resting) to match the
+/// existing header status indicator in the TUI.
+const TITLE_FRAMES: &[&str] = &["🐳", "🐋", "🐳", "🐋"];
+const TITLE_ANIMATION_INTERVAL: Duration = Duration::from_millis(800);
+
+/// Shared flag controlling the title animation loop. Set to `true` by
+/// `start_title_animation()`, cleared by `stop_title_animation()`.
+static TITLE_ANIMATION_RUNNING: AtomicBool = AtomicBool::new(false);
+
+/// Write OSC 0 (set window title) sequence.
+fn set_terminal_title(title: &str) {
+    let seq = format!("\x1b]0;{title}\x07");
+    let mut stdout = io::stdout();
+    let _ = stdout.write_all(seq.as_bytes());
+    let _ = stdout.flush();
+}
+
+/// Tracks whether the ✅ completion marker was set, so
+/// `reset_title_on_interaction()` can skip redundant writes.
+static COMPLETION_MARKER_SHOWN: AtomicBool = AtomicBool::new(false);
+
+/// Start an animated terminal title spinner.
+///
+/// Cycles the terminal title between 🐳→🐋 every 800ms while processing,
+/// matching the whale status indicator in the TUI header, so alt-tabbed
+/// users can see activity.
+///
+/// The animation runs in a background tokio task that checks
+/// `TITLE_ANIMATION_RUNNING`. Each call restarts the animation with the
+/// given `original` base title — safe to call on every turn start.
+pub fn start_title_animation(original: &str) {
+    // Signal any existing animation loop to exit, then start fresh.
+    TITLE_ANIMATION_RUNNING.store(true, Ordering::SeqCst);
+    let base = original.to_string();
+    tokio::spawn(async move {
+        let mut frame = 0usize;
+        while TITLE_ANIMATION_RUNNING.load(Ordering::SeqCst) {
+            // Yield once per frame so a racing stop_title_animation()
+            // can observe the cleared flag and apply the completion
+            // marker before the next frame write. Without this yield
+            // the background task could overwrite the ✅ marker with
+            // the next whale frame.
+            tokio::task::yield_now().await;
+            if !TITLE_ANIMATION_RUNNING.load(Ordering::SeqCst) {
+                break;
+            }
+            let spinner = TITLE_FRAMES[frame % TITLE_FRAMES.len()];
+            set_terminal_title(&format!("{spinner} {base}"));
+            frame += 1;
+            tokio::time::sleep(TITLE_ANIMATION_INTERVAL).await;
+        }
+        // Don't restore title here — stop_title_animation() handles
+        // what to show on completion (e.g. ✅ marker).
+    });
+}
+
+/// Stop the title animation and show a completion marker.
+///
+/// Sets the title to `✅ <base>` so alt-tabbed users see at a glance
+/// that processing finished. The marker is overwritten on the next turn
+/// by [`start_title_animation`].
+pub fn stop_title_animation() {
+    TITLE_ANIMATION_RUNNING.store(false, Ordering::SeqCst);
+    COMPLETION_MARKER_SHOWN.store(false, Ordering::SeqCst);
+    // Show ✅ marker only for beep mode. Bell mode already has its own
+    // terminal-level visual indicator (flash/icon).
+    let mode = COMPLETION_SOUND_MODE.load(Ordering::SeqCst);
+    if mode == 1 {
+        set_terminal_title("✅ CodeWhale");
+    }
+    play_completion_sound();
+}
+
+/// Clear the ✅ completion marker from the title when the user interacts.
+///
+/// Call this on every user input event (key press, mouse click) so the
+/// marker doesn't persist once the user is back at the terminal.
+pub fn reset_title_on_interaction() {
+    if COMPLETION_MARKER_SHOWN.swap(false, Ordering::SeqCst) {
+        set_terminal_title("CodeWhale");
+    }
+}
+
+/// Completion sound mode (0 = off, 1 = beep, 2 = bell).
+static COMPLETION_SOUND_MODE: AtomicU8 = AtomicU8::new(1);
+
+/// Set the completion sound mode from config.
+/// Call once at startup or on `/settings` change.
+pub fn set_completion_sound_mode(mode: crate::config::CompletionSound) {
+    let val = match mode {
+        crate::config::CompletionSound::Off => 0u8,
+        crate::config::CompletionSound::Beep => 1u8,
+        crate::config::CompletionSound::Bell => 2u8,
+    };
+    COMPLETION_SOUND_MODE.store(val, Ordering::SeqCst);
+}
+
+/// Play the configured completion sound (if not `Off`).
+pub fn play_completion_sound() {
+    match COMPLETION_SOUND_MODE.load(Ordering::SeqCst) {
+        0 => {} // Off
+        1 => {
+            beep_sound();
+        }
+        2 => {
+            bell_sound();
+        }
+        _ => {}
+    }
+}
+
+/// Play a short completion sound via the system beep.
+///
+/// On Windows uses `MessageBeep(MB_OK)` which plays the default system
+/// notification sound. On other platforms writes `BEL` (`\x07`) to stdout.
+#[cfg(target_os = "windows")]
+fn beep_sound() {
+    windows_bell();
+}
+
+/// Non-Windows: write BEL to stdout for the terminal bell.
+#[cfg(not(target_os = "windows"))]
+fn beep_sound() {
+    let _ = io::stdout().write_all(b"\x07");
+}
+
+/// Pure terminal BEL character.
+fn bell_sound() {
+    let _ = io::stdout().write_all(b"\x07");
+}
+
+/// Show a macOS Notification Center alert via `osascript`.
+///
+/// Runs on a dedicated background thread so the caller is not blocked.
+///
+/// The notification includes:
+/// - **Title**: "CodeWhale"
+/// - **Subtitle**: First line of `msg` (when the message contains a newline,
+///   e.g. the response preview from a completed turn)
+/// - **Body**: Remaining lines of `msg`, or the full `msg` if single-line
+/// - **Sound**: Default macOS notification sound
+///
+/// The message body is capped at 200 **characters** (not bytes) to keep the
+/// bubble readable while correctly handling multi-byte text.
+///
+/// **Security**: The message is passed to `osascript` as a command-line
+/// argument via `ARGV`, never embedded inline in the AppleScript source.
+/// AppleScript does not treat backslash as an escape inside double-quoted
+/// string literals, so the previous `\"` approach would terminate the
+/// string at the `"` and leave any text between unbalanced quotes
+/// evaluated as raw AppleScript code — a code-injection vector for
+/// AI-generated notification text. Passing via `ARGV` avoids this
+/// entirely because the message is never parsed as AppleScript syntax.
+///
+/// This is best-effort: if `osascript` is not available (e.g. headless SSH
+/// session) the error is logged via `tracing::warn!` instead of silently
+/// swallowed.
+#[cfg(target_os = "macos")]
+fn macos_display_notification(msg: &str) {
+    let body = msg.to_string();
+
+    // Spawn on a background thread so we don't block the caller.
+    // osascript itself is fast (~50 ms), but spawning a subprocess
+    // synchronously from an async context steals a tokio thread.
+    let _ = std::thread::Builder::new()
+        .name("osascript-notif".into())
+        .spawn(move || {
+            // Char-bounded truncation (not byte-bounded) so we don't slice
+            // through a multi-byte sequence and emit invalid UTF-8.
+            let body_str: String = body.chars().take(200).collect();
+
+            // Build AppleScript that receives the message via ARGV
+            // instead of inline string interpolation. AppleScript does
+            // not treat backslash as an escape inside double-quoted
+            // string literals, so `\"` would terminate the string at
+            // the `"` and leave a dangling `\`. Passing the message as
+            // a command-line argument avoids any injection risk.
+            //
+            // When the message has multiple lines, the first line
+            // becomes the subtitle and the rest becomes the body —
+            // this lets turn notifications show the response preview
+            // in the subtitle and the duration/cost summary in the body.
+            let mut args: Vec<String> = Vec::new();
+
+            if let Some(idx) = body_str.find('\n') {
+                let subtitle = body_str[..idx].trim();
+                let body_text = body_str[idx + 1..].trim();
+                args.extend_from_slice(&[
+                    "-e".into(),
+                    "on run argv".into(),
+                    "-e".into(),
+                    "set theBody to item 1 of argv".into(),
+                    "-e".into(),
+                    "set theSubtitle to item 2 of argv".into(),
+                    "-e".into(),
+                    "display notification theBody with title \"CodeWhale\" subtitle theSubtitle sound name \"default\"".into(),
+                    "-e".into(),
+                    "end run".into(),
+                    "--".into(),
+                    body_text.into(),
+                    subtitle.into(),
+                ]);
+            } else {
+                args.extend_from_slice(&[
+                    "-e".into(),
+                    "on run argv".into(),
+                    "-e".into(),
+                    "display notification (item 1 of argv) with title \"CodeWhale\" sound name \"default\"".into(),
+                    "-e".into(),
+                    "end run".into(),
+                    "--".into(),
+                    body_str,
+                ]);
+            }
+
+            match std::process::Command::new("osascript")
+                .args(&args)
+                .output()
+            {
+                Ok(output) if !output.status.success() => {
+                    let stderr = String::from_utf8_lossy(&output.stderr);
+                    tracing::warn!(stderr = %stderr, "osascript notification failed");
+                }
+                Err(e) => {
+                    tracing::warn!(error = %e, "osascript notification error");
+                }
+                _ => {}
+            }
+        });
+}
+
 /// Return a human-readable duration string, capped at two units so
 /// it stays compact in headers and notifications.
 ///
@@ -289,6 +574,8 @@ use crate::tui::app::App;
 /// `Off`).
 pub fn settings(config: &crate::config::Config) -> Option<(Method, Duration, bool)> {
     let notif = config.notifications_config();
+    // Initialize completion sound mode from config.
+    set_completion_sound_mode(notif.completion_sound);
     let method = match notif.method {
         crate::config::NotificationMethod::Auto => Method::Auto,
         crate::config::NotificationMethod::Osc9 => Method::Osc9,
@@ -447,7 +734,9 @@ mod tests {
     /// when the test harness runs them in parallel threads.
     fn env_lock() -> std::sync::MutexGuard<'static, ()> {
         static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
-        LOCK.get_or_init(|| Mutex::new(())).lock().unwrap()
+        LOCK.get_or_init(|| Mutex::new(()))
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
     }
 
     fn capture(
@@ -620,7 +909,7 @@ mod tests {
     }
 
     #[test]
-    #[cfg(not(target_os = "windows"))]
+    #[cfg(not(any(target_os = "windows", target_os = "macos")))]
     fn auto_detect_picks_bel_for_unknown_on_unix() {
         let _lock = env_lock();
         let prev_tp = std::env::var_os("TERM_PROGRAM");
@@ -654,12 +943,11 @@ mod tests {
         assert_eq!(resolved, Method::Bel);
     }
 
-    /// #583: on Windows, an unknown TERM_PROGRAM resolves to `Off`
-    /// (not `Bel`) so the post-turn notification doesn't ring the
-    /// `SystemAsterisk` / `MB_OK` chime.
+    /// #2166: on Windows, an unknown TERM_PROGRAM resolves to `Bel` so
+    /// `windows_bell()` can route the notification through `MessageBeep`.
     #[test]
     #[cfg(target_os = "windows")]
-    fn auto_detect_picks_off_for_unknown_on_windows() {
+    fn auto_detect_picks_bel_for_unknown_on_windows() {
         let _lock = env_lock();
         let prev = std::env::var_os("TERM_PROGRAM");
         // SAFETY: test-only; serialised by env_lock().
@@ -672,7 +960,7 @@ mod tests {
                 None => std::env::remove_var("TERM_PROGRAM"),
             }
         }
-        assert_eq!(resolved, Method::Off);
+        assert_eq!(resolved, Method::Bel);
     }
 
     /// #583: known OSC-9 terminals must still resolve to `Osc9` on
@@ -704,7 +992,7 @@ mod tests {
     /// `TERM_PROGRAM` but do set `TERM=xterm-ghostty`. The `$TERM`
     /// fallback should catch them.
     #[test]
-    #[cfg(not(target_os = "windows"))]
+    #[cfg(not(any(target_os = "windows", target_os = "macos")))]
     fn auto_detect_picks_osc9_for_xterm_ghostty_term_fallback() {
         let _lock = env_lock();
         let prev_tp = std::env::var_os("TERM_PROGRAM");
@@ -772,7 +1060,7 @@ mod tests {
     }
 
     #[test]
-    #[cfg(not(target_os = "windows"))]
+    #[cfg(not(any(target_os = "windows", target_os = "macos")))]
     fn auto_detect_picks_kitty_from_term_fallback() {
         let _lock = env_lock();
         let prev_tp = std::env::var_os("TERM_PROGRAM");
@@ -805,8 +1093,11 @@ mod tests {
 
     /// When neither `TERM_PROGRAM` nor `TERM` suggests a known capable
     /// terminal, the fallback on Unix is `Bel`.
+    ///
+    /// On macOS the `MacOS` method takes priority, so this test is
+    /// excluded there.
     #[test]
-    #[cfg(not(target_os = "windows"))]
+    #[cfg(not(any(target_os = "windows", target_os = "macos")))]
     fn auto_detect_falls_back_to_bel_for_unrelated_term() {
         let _lock = env_lock();
         let prev_tp = std::env::var_os("TERM_PROGRAM");
diff --git a/crates/tui/src/tui/onboarding/mod.rs b/crates/tui/src/tui/onboarding/mod.rs
index 4c7741d5..a1cce682 100644
--- a/crates/tui/src/tui/onboarding/mod.rs
+++ b/crates/tui/src/tui/onboarding/mod.rs
@@ -22,11 +22,12 @@ pub fn render(f: &mut Frame, area: Rect, app: &App) {
     let block = Block::default().style(Style::default().bg(palette::DEEPSEEK_INK));
     f.render_widget(block, area);
 
+    const TOP_MARGIN: u16 = 2;
     let content_width = 76.min(area.width.saturating_sub(4));
-    let content_height = 20.min(area.height.saturating_sub(4));
+    let content_height = 20.min(area.height.saturating_sub(TOP_MARGIN + 2));
     let content_area = Rect {
-        x: (area.width - content_width) / 2,
-        y: (area.height - content_height) / 2,
+        x: (area.width.saturating_sub(content_width)) / 2,
+        y: TOP_MARGIN,
         width: content_width,
         height: content_height,
     };
@@ -127,7 +128,13 @@ pub fn tips_lines(app: &App) -> Vec<ratatui::text::Line<'static>> {
 }
 
 pub fn default_marker_path() -> Option<PathBuf> {
-    dirs::home_dir().map(|home| home.join(".deepseek").join(".onboarded"))
+    dirs::home_dir().map(|home| {
+        let primary = home.join(".codewhale").join(".onboarded");
+        if primary.exists() {
+            return primary;
+        }
+        home.join(".deepseek").join(".onboarded")
+    })
 }
 
 pub fn is_onboarded() -> bool {
diff --git a/crates/tui/src/tui/paste.rs b/crates/tui/src/tui/paste.rs
index c7c67af5..243b3ea0 100644
--- a/crates/tui/src/tui/paste.rs
+++ b/crates/tui/src/tui/paste.rs
@@ -49,15 +49,24 @@ pub fn handle_paste_burst_key(app: &mut App, key: &KeyEvent, now: Instant) -> bo
         }
         KeyCode::Char(c) if !has_ctrl_alt_or_super => {
             if !c.is_ascii() {
+                // IME-committed characters (Chinese, Japanese, Korean)
+                // arrive as individual KeyCode::Char events, typically with
+                // tens-of-milliseconds gaps between each committed character.
+                // Paste-burst buffering would lose characters when the IME
+                // commits slower than the burst heuristic's timing window.
+                //
+                // We still call note_plain_char + extend_window so that:
+                //   1. The burst timing counter advances for non-IME fast
+                //      typing on terminals without bracketed paste support.
+                //   2. The Enter-suppression window stays open during a rapid
+                //      non-ASCII sequence, preventing premature submission.
+                // But the character is inserted directly into the composer
+                // rather than placed into the paste-burst buffer.
                 if let Some(pending) = app.paste_burst.flush_before_modified_input() {
                     app.insert_str(&pending);
                 }
-                if app.paste_burst.try_append_char_if_active(c, now) {
-                    return true;
-                }
-                if let Some(decision) = app.paste_burst.on_plain_char_no_hold(now) {
-                    return handle_paste_burst_decision(app, decision, c, now);
-                }
+                app.paste_burst.note_plain_char(now);
+                app.paste_burst.extend_window(now);
                 app.insert_char(c);
                 return true;
             }
@@ -190,10 +199,9 @@ mod tests {
             );
         }
 
-        assert!(app.flush_paste_burst_if_due(
-            t0 + Duration::from_millis(pasted.chars().count() as u64)
-                + crate::tui::paste_burst::PasteBurst::recommended_active_flush_delay()
-        ));
+        // Non-ASCII characters are now inserted directly into the composer
+        // rather than buffered by paste burst. The Enter suppression window
+        // kept the newline from submitting prematurely.
         assert_eq!(app.input, pasted);
     }
 
diff --git a/crates/tui/src/tui/paste_burst.rs b/crates/tui/src/tui/paste_burst.rs
index 62788451..ef1fe24c 100644
--- a/crates/tui/src/tui/paste_burst.rs
+++ b/crates/tui/src/tui/paste_burst.rs
@@ -77,6 +77,7 @@ impl PasteBurst {
         CharDecision::RetainFirstChar
     }
 
+    #[allow(dead_code)]
     pub fn on_plain_char_no_hold(&mut self, now: Instant) -> Option<CharDecision> {
         self.note_plain_char(now);
 
@@ -94,7 +95,7 @@ impl PasteBurst {
         None
     }
 
-    fn note_plain_char(&mut self, now: Instant) {
+    pub(crate) fn note_plain_char(&mut self, now: Instant) {
         match self.last_plain_char_time {
             Some(prev) if now.duration_since(prev) <= PASTE_BURST_CHAR_INTERVAL => {
                 self.consecutive_plain_char_burst =
@@ -176,6 +177,7 @@ impl PasteBurst {
         self.burst_window_until = Some(now + PASTE_ENTER_SUPPRESS_WINDOW);
     }
 
+    #[allow(dead_code)]
     pub fn try_append_char_if_active(&mut self, ch: char, now: Instant) -> bool {
         if self.active || !self.buffer.is_empty() {
             self.append_char_to_buffer(ch, now);
@@ -225,12 +227,27 @@ impl PasteBurst {
         Some(out)
     }
 
-    pub fn clear_window_after_non_char(&mut self) {
+    /// Reset burst-accumulation state without clearing the suppression window.
+    ///
+    /// Used when a non-char key (Tab, etc.) arrives during an active burst as
+    /// part of table-data paste. The buffer was flushed upstream; only the
+    /// active state is reset so `burst_window_until` stays alive and a trailing
+    /// Enter is still absorbed as a newline (#2134).
+    ///
+    /// # Panics
+    ///
+    /// Panics in debug builds if `buffer` is non-empty — the caller must flush
+    /// via [`flush_before_modified_input`] first.
+    pub fn deactivate_keep_window(&mut self) {
+        debug_assert!(
+            self.buffer.is_empty(),
+            "buffer must be flushed before deactivating"
+        );
         self.consecutive_plain_char_burst = 0;
         self.last_plain_char_time = None;
-        self.burst_window_until = None;
         self.active = false;
         self.pending_first_char = None;
+        // burst_window_until intentionally NOT cleared
     }
 
     pub fn is_active(&self) -> bool {
@@ -332,4 +349,47 @@ mod tests {
         let due = t0 + Duration::from_millis(20);
         assert_eq!(burst.next_flush_delay(due), Some(Duration::ZERO));
     }
+
+    /// Simulate #2134: when a non-char key (Tab) arrives during table-data
+    /// paste, `deactivate_keep_window` resets accumulation state but
+    /// preserves the Enter-suppression window so a trailing newline is still
+    /// absorbed instead of submitting the partial input.
+    #[test]
+    fn deactivate_keep_window_preserves_enter_suppression_window() {
+        let mut burst = PasteBurst::default();
+        let t0 = Instant::now();
+
+        assert!(matches!(
+            burst.on_plain_char('a', t0),
+            CharDecision::RetainFirstChar
+        ));
+        let t1 = t0 + Duration::from_millis(1);
+        assert!(matches!(
+            burst.on_plain_char('b', t1),
+            CharDecision::BeginBufferFromPending
+        ));
+        burst.append_char_to_buffer('b', t1);
+        assert!(burst.is_active());
+        assert!(burst.newline_should_insert_instead_of_submit(t1));
+
+        let flushed = burst.flush_before_modified_input();
+        assert!(flushed.is_some());
+        assert!(!burst.is_active());
+
+        burst.deactivate_keep_window();
+
+        assert!(!burst.is_active());
+
+        let t_tab = t1 + Duration::from_millis(2);
+        assert!(
+            burst.newline_should_insert_instead_of_submit(t_tab),
+            "Enter within suppression window should insert newline, not submit"
+        );
+
+        let t_expired = t_tab + PASTE_ENTER_SUPPRESS_WINDOW + Duration::from_millis(1);
+        assert!(
+            !burst.newline_should_insert_instead_of_submit(t_expired),
+            "Enter after suppression window expires should submit"
+        );
+    }
 }
diff --git a/crates/tui/src/tui/provider_picker.rs b/crates/tui/src/tui/provider_picker.rs
index ecf9f722..8fb3ef1c 100644
--- a/crates/tui/src/tui/provider_picker.rs
+++ b/crates/tui/src/tui/provider_picker.rs
@@ -21,12 +21,12 @@ use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
 use ratatui::{
     buffer::Buffer,
     layout::{Constraint, Direction, Layout, Rect},
-    style::{Modifier, Style},
+    style::{Color, Modifier, Style},
     text::{Line, Span},
     widgets::{Block, Borders, Clear, Paragraph, Widget},
 };
 
-use crate::config::{ApiProvider, Config, has_api_key_for};
+use crate::config::{ApiProvider, Config, has_api_key_for, kimi_cli_credentials_present};
 use crate::palette;
 use crate::tui::views::{ModalKind, ModalView, ViewAction, ViewEvent};
 
@@ -65,13 +65,23 @@ impl ProviderPickerView {
     }
 
     fn move_up(&mut self) {
-        if self.selected_idx > 0 {
+        if self.providers.is_empty() {
+            return;
+        }
+        if self.selected_idx == 0 {
+            self.selected_idx = self.providers.len() - 1;
+        } else {
             self.selected_idx -= 1;
         }
     }
 
     fn move_down(&mut self) {
-        if self.selected_idx + 1 < self.providers.len() {
+        if self.providers.is_empty() {
+            return;
+        }
+        if self.selected_idx + 1 == self.providers.len() {
+            self.selected_idx = 0;
+        } else {
             self.selected_idx += 1;
         }
     }
@@ -91,9 +101,12 @@ impl ProviderPickerView {
             ApiProvider::Openai => "OPENAI_API_KEY",
             ApiProvider::Atlascloud => "ATLASCLOUD_API_KEY",
             ApiProvider::WanjieArk => "WANJIE_ARK_API_KEY",
+            ApiProvider::Volcengine => "VOLCENGINE_API_KEY",
             ApiProvider::Openrouter => "OPENROUTER_API_KEY",
+            ApiProvider::XiaomiMimo => "XIAOMI_MIMO_API_KEY / MIMO_API_KEY",
             ApiProvider::Novita => "NOVITA_API_KEY",
             ApiProvider::Fireworks => "FIREWORKS_API_KEY",
+            ApiProvider::Moonshot => "MOONSHOT_API_KEY / KIMI_API_KEY",
             ApiProvider::Sglang => "SGLANG_API_KEY",
             ApiProvider::Vllm => "VLLM_API_KEY",
             ApiProvider::Ollama => "OLLAMA_API_KEY",
@@ -102,6 +115,9 @@ impl ProviderPickerView {
 
     fn provider_hint(provider: ApiProvider, has_key: bool) -> String {
         match provider {
+            ApiProvider::Moonshot if kimi_cli_credentials_present() => {
+                "(Kimi CLI OAuth ready)".to_string()
+            }
             ApiProvider::Ollama => "self-hosted; defaults to http://localhost:11434".to_string(),
             ApiProvider::Sglang | ApiProvider::Vllm if has_key => {
                 "(configured; optional key)".to_string()
@@ -112,6 +128,28 @@ impl ProviderPickerView {
         }
     }
 
+    fn visible_start(&self, visible_rows: usize) -> usize {
+        if visible_rows == 0 {
+            return 0;
+        }
+        let max_start = self.providers.len().saturating_sub(visible_rows);
+        self.selected_idx
+            .saturating_add(1)
+            .saturating_sub(visible_rows)
+            .min(max_start)
+    }
+
+    fn selected_row_style(fg: Color) -> Style {
+        Style::default()
+            .fg(fg)
+            .bg(palette::SURFACE_ELEVATED)
+            .add_modifier(Modifier::BOLD)
+    }
+
+    fn selected_row_bg_style() -> Style {
+        Style::default().bg(palette::SURFACE_ELEVATED)
+    }
+
     fn render_list(&self, area: Rect, buf: &mut Buffer) {
         let outer = Block::default()
             .title(Line::from(Span::styled(
@@ -134,39 +172,64 @@ impl ProviderPickerView {
         let inner = outer.inner(area);
         outer.render(area, buf);
 
-        let mut lines: Vec<Line> = Vec::with_capacity(self.providers.len());
-        for (idx, (provider, has_key)) in self.providers.iter().enumerate() {
+        let visible_rows = usize::from(inner.height);
+        let visible_start = self.visible_start(visible_rows);
+        let mut lines: Vec<Line> = Vec::with_capacity(visible_rows);
+        for (idx, (provider, has_key)) in self
+            .providers
+            .iter()
+            .enumerate()
+            .skip(visible_start)
+            .take(visible_rows)
+        {
             let is_selected = idx == self.selected_idx;
             let is_active = *provider == self.active_provider;
             let arrow = if is_selected { "▸" } else { " " };
             let active_dot = if is_active { " *" } else { "  " };
-            let label_style = if is_selected {
+            let spacer_style = if is_selected {
+                Self::selected_row_bg_style()
+            } else {
                 Style::default()
-                    .fg(palette::SELECTION_TEXT)
-                    .bg(palette::SELECTION_BG)
-                    .add_modifier(Modifier::BOLD)
+            };
+            let label_style = if is_selected {
+                Self::selected_row_style(palette::TEXT_PRIMARY)
             } else {
                 Style::default().fg(palette::TEXT_PRIMARY)
             };
             let hint_style = if is_selected {
-                Style::default()
-                    .fg(palette::SELECTION_TEXT)
-                    .bg(palette::SELECTION_BG)
+                let hint_fg = if *has_key {
+                    palette::TEXT_MUTED
+                } else {
+                    palette::STATUS_WARNING
+                };
+                Self::selected_row_style(hint_fg)
             } else if *has_key {
                 Style::default().fg(palette::TEXT_MUTED)
             } else {
                 Style::default().fg(palette::STATUS_WARNING)
             };
             let hint = Self::provider_hint(*provider, *has_key);
-            lines.push(Line::from(vec![
-                Span::raw(" "),
+            let mut line = Line::from(vec![
+                Span::styled(" ", spacer_style),
                 Span::styled(arrow, label_style),
-                Span::raw(" "),
+                Span::styled(" ", spacer_style),
                 Span::styled(provider.display_name().to_string(), label_style),
                 Span::styled(active_dot, label_style),
-                Span::raw("  "),
+                Span::styled("  ", spacer_style),
                 Span::styled(hint, hint_style),
-            ]));
+            ]);
+            if is_selected {
+                line.style = Self::selected_row_bg_style();
+                let target_width = usize::from(inner.width);
+                let line_width = line.width();
+                if line_width < target_width {
+                    line.spans.push(Span::styled(
+                        " ".repeat(target_width - line_width),
+                        Self::selected_row_bg_style(),
+                    ));
+                }
+            }
+            lines.push(line);
         }
         Paragraph::new(lines).render(inner, buf);
     }
@@ -287,6 +350,10 @@ impl ModalView for ProviderPickerView {
                     let provider = self.selected_provider();
                     if self.selected_has_key() {
                         ViewAction::EmitAndClose(ViewEvent::ProviderPickerApplied { provider })
+                    } else if provider == ApiProvider::Moonshot && kimi_cli_credentials_present() {
+                        ViewAction::EmitAndClose(ViewEvent::ProviderPickerKimiOAuthEnabled {
+                            provider,
+                        })
                     } else {
                         self.stage = Stage::KeyEntry;
                         self.api_key_input.clear();
@@ -339,7 +406,7 @@ impl ModalView for ProviderPickerView {
     fn render(&self, area: Rect, buf: &mut Buffer) {
         let popup_width = 64.min(area.width.saturating_sub(4)).max(40);
         let popup_height = match self.stage {
-            Stage::List => 12,
+            Stage::List => (self.providers.len() as u16).saturating_add(2),
             Stage::KeyEntry => 10,
         }
         .min(area.height.saturating_sub(4))
@@ -380,6 +447,16 @@ mod tests {
         panic!("provider {provider:?} not found in picker");
     }
 
+    fn render_text(picker: &ProviderPickerView, width: u16, height: u16) -> String {
+        let area = Rect::new(0, 0, width, height);
+        let mut buf = Buffer::empty(area);
+        picker.render(area, &mut buf);
+        (0..height)
+            .map(|y| (0..width).map(|x| buf[(x, y)].symbol()).collect::<String>())
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+
     #[test]
     fn picker_lists_all_providers() {
         let config = Config::default();
@@ -398,8 +475,10 @@ mod tests {
                 "AtlasCloud",
                 "Wanjie Ark",
                 "OpenRouter",
+                "Xiaomi MiMo",
                 "Novita AI",
                 "Fireworks AI",
+                "Moonshot/Kimi",
                 "SGLang",
                 "vLLM",
                 "Ollama"
@@ -431,6 +510,18 @@ mod tests {
         assert_eq!(picker.active_provider, ApiProvider::Openrouter);
     }
 
+    #[test]
+    fn list_navigation_wraps_between_first_and_last_provider() {
+        let config = Config::default();
+        let mut picker = ProviderPickerView::new(ApiProvider::Deepseek, &config);
+
+        picker.handle_key(key(KeyCode::Up));
+        assert_eq!(picker.selected_provider(), ApiProvider::Ollama);
+
+        picker.handle_key(key(KeyCode::Down));
+        assert_eq!(picker.selected_provider(), ApiProvider::Deepseek);
+    }
+
     #[test]
     fn enter_with_no_key_transitions_to_key_entry_stage() {
         let config = Config::default();
@@ -450,8 +541,7 @@ mod tests {
             ..Config::default()
         };
         let mut picker = ProviderPickerView::new(ApiProvider::NvidiaNim, &config);
-        // Move up twice to DeepSeek (index 0), which has a key from the config.
-        picker.handle_key(key(KeyCode::Up));
+        // Move up once to DeepSeek (index 0), which has a key from the config.
         picker.handle_key(key(KeyCode::Up));
         let action = picker.handle_key(key(KeyCode::Enter));
         match action {
@@ -520,4 +610,59 @@ mod tests {
         }
         assert_eq!(picker.api_key_input, "abcdef");
     }
+
+    #[test]
+    fn small_list_render_keeps_selected_provider_visible_after_down_navigation() {
+        let config = Config::default();
+        let mut picker = ProviderPickerView::new(ApiProvider::Deepseek, &config);
+        move_to_provider(&mut picker, ApiProvider::Ollama);
+
+        let rendered = render_text(&picker, 80, 12);
+
+        assert!(rendered.contains("Ollama"));
+        assert!(!rendered.contains("DeepSeek *"));
+    }
+
+    #[test]
+    fn small_list_render_keeps_initial_active_provider_visible() {
+        let config = Config::default();
+        let picker = ProviderPickerView::new(ApiProvider::Ollama, &config);
+
+        let rendered = render_text(&picker, 80, 12);
+
+        assert!(rendered.contains("Ollama *"));
+    }
+
+    #[test]
+    fn tall_list_render_shows_all_providers_without_scrolling() {
+        let config = Config::default();
+        let picker = ProviderPickerView::new(ApiProvider::Deepseek, &config);
+
+        let rendered = render_text(&picker, 80, 20);
+
+        assert!(rendered.contains("DeepSeek *"));
+        assert!(rendered.contains("Ollama"));
+    }
+
+    #[test]
+    fn selected_provider_row_uses_strong_highlight() {
+        let config = Config::default();
+        let picker = ProviderPickerView::new(ApiProvider::Deepseek, &config);
+        let area = Rect::new(0, 0, 80, 20);
+        let mut buf = Buffer::empty(area);
+
+        picker.render(area, &mut buf);
+
+        let highlighted_cells = area
+            .positions()
+            .filter(|position| {
+                let cell = &buf[*position];
+                cell.bg == palette::SURFACE_ELEVATED
+            })
+            .count();
+        assert!(
+            highlighted_cells >= 32,
+            "selected provider row should use a visible continuous highlight"
+        );
+    }
 }
diff --git a/crates/tui/src/tui/scrolling.rs b/crates/tui/src/tui/scrolling.rs
index 6bc51781..1e976b64 100644
--- a/crates/tui/src/tui/scrolling.rs
+++ b/crates/tui/src/tui/scrolling.rs
@@ -17,6 +17,8 @@
 
 use std::time::{Duration, Instant};
 
+use crate::tui::ui_text::CopyLineSeparator;
+
 const TRACKPAD_EVENT_WINDOW: Duration = Duration::from_millis(35);
 const WHEEL_LINES_PER_TICK: i32 = 3;
 const TRACKPAD_BASE_LINES_PER_TICK: i32 = 1;
@@ -36,6 +38,8 @@ pub enum TranscriptLineMeta {
     CellLine {
         cell_index: usize,
         line_in_cell: usize,
+        copy_prefix_width: usize,
+        copy_separator_after: CopyLineSeparator,
     },
     Spacer,
 }
@@ -48,10 +52,32 @@ impl TranscriptLineMeta {
             TranscriptLineMeta::CellLine {
                 cell_index,
                 line_in_cell,
+                ..
             } => Some((cell_index, line_in_cell)),
             TranscriptLineMeta::Spacer => None,
         }
     }
+
+    #[must_use]
+    pub fn copy_separator_after(&self) -> CopyLineSeparator {
+        match *self {
+            TranscriptLineMeta::CellLine {
+                copy_separator_after,
+                ..
+            } => copy_separator_after,
+            TranscriptLineMeta::Spacer => CopyLineSeparator::Newline,
+        }
+    }
+
+    #[must_use]
+    pub fn copy_prefix_width(&self) -> usize {
+        match *self {
+            TranscriptLineMeta::CellLine {
+                copy_prefix_width, ..
+            } => copy_prefix_width,
+            TranscriptLineMeta::Spacer => 0,
+        }
+    }
 }
 
 // === Transcript Scroll State ===
@@ -271,6 +297,8 @@ mod tests {
         TranscriptLineMeta::CellLine {
             cell_index,
             line_in_cell,
+            copy_prefix_width: 0,
+            copy_separator_after: CopyLineSeparator::Newline,
         }
     }
 
diff --git a/crates/tui/src/tui/session_picker.rs b/crates/tui/src/tui/session_picker.rs
index f6a80639..1cfbad95 100644
--- a/crates/tui/src/tui/session_picker.rs
+++ b/crates/tui/src/tui/session_picker.rs
@@ -952,6 +952,7 @@ mod tests {
             cost: crate::session_manager::SessionCostSnapshot::default(),
             parent_session_id: None,
             forked_from_message_count: None,
+            cumulative_turn_secs: 0,
         }
     }
 
diff --git a/crates/tui/src/tui/sidebar.rs b/crates/tui/src/tui/sidebar.rs
index bff5c51a..40a65e80 100644
--- a/crates/tui/src/tui/sidebar.rs
+++ b/crates/tui/src/tui/sidebar.rs
@@ -7,6 +7,8 @@
 use std::fmt::Write;
 use std::time::{Duration, Instant};
 
+use crate::tui::app::HuntVerdict;
+
 use ratatui::{
     Frame,
     layout::{Constraint, Direction, Layout, Rect},
@@ -22,7 +24,7 @@ use crate::tools::plan::StepStatus;
 use crate::tools::subagent::SubAgentStatus;
 use crate::tools::todo::TodoStatus;
 
-use super::app::{App, SidebarFocus, TaskPanelEntry};
+use super::app::{App, SidebarFocus, SidebarHoverSection, SidebarHoverState, TaskPanelEntry};
 use super::history::{GenericToolCell, HistoryCell, ToolCell, ToolStatus, summarize_tool_output};
 use super::subagent_routing::active_fanout_counts;
 use super::ui_text::{concise_shell_command_label, truncate_line_to_width};
@@ -35,7 +37,9 @@ const RECENT_TOOL_SCAN_LIMIT: usize = 24;
 const ACTIVE_TOOL_COMPLETED_ROW_TTL: Duration = Duration::from_secs(8);
 const ACTIVE_TOOL_STALE_RUNNING_ROW_TTL: Duration = Duration::from_secs(600);
 
-pub fn render_sidebar(f: &mut Frame, area: Rect, app: &App) {
+pub fn render_sidebar(f: &mut Frame, area: Rect, app: &mut App) {
+    // Clear hover state at the start of each render
+    app.sidebar_hover = SidebarHoverState::default();
     if area.width < 24 || area.height < 8 {
         // Paint a styled block over the area so stale cells from a previous
         // (wider) frame don't persist as bleed-through artifacts (#400).
@@ -60,7 +64,7 @@ pub fn render_sidebar(f: &mut Frame, area: Rect, app: &App) {
 /// Build the Auto-mode panel stack. Empty panels collapse to zero height so
 /// non-empty ones get the full sidebar real estate. Work appears when it has
 /// useful content, or as the one quiet empty state when nothing else is active.
-fn render_sidebar_auto(f: &mut Frame, area: Rect, app: &App) {
+fn render_sidebar_auto(f: &mut Frame, area: Rect, app: &mut App) {
     let work_has_content = sidebar_work_summary(app).has_useful_content();
     let tasks_empty = app.runtime_turn_id.is_none() && app.task_panel.is_empty();
     let agents_empty = app.subagent_cache.is_empty()
@@ -226,10 +230,10 @@ impl SidebarWorkSummary {
 
 fn sidebar_work_summary(app: &App) -> SidebarWorkSummary {
     let mut summary = SidebarWorkSummary {
-        goal_objective: app.goal.goal_objective.clone(),
-        goal_token_budget: app.goal.goal_token_budget,
-        goal_completed: app.goal.goal_completed,
-        goal_started_at: app.goal.goal_started_at,
+        goal_objective: app.hunt.quarry.clone(),
+        goal_token_budget: app.hunt.token_budget,
+        goal_completed: app.hunt.verdict == HuntVerdict::Hunted,
+        goal_started_at: app.hunt.started_at,
         tokens_used: app.session.total_conversation_tokens,
         cycle_count: app.cycle_count,
         ..SidebarWorkSummary::default()
@@ -440,7 +444,7 @@ fn push_work_checklist_lines(
         let (prefix, color) = match item.status {
             TodoStatus::Pending => ("[ ]", palette::TEXT_MUTED),
             TodoStatus::InProgress => ("[~]", palette::STATUS_WARNING),
-            TodoStatus::Completed => ("[x]", palette::STATUS_SUCCESS),
+            TodoStatus::Completed => ("[✓]", palette::STATUS_SUCCESS),
         };
         let text = format!("{prefix} #{} {}", item.id, item.content);
         lines.push(Line::from(Span::styled(
@@ -531,7 +535,7 @@ fn push_work_strategy_lines(
         let (prefix, color) = match step.status {
             StepStatus::Pending => ("[ ]", theme.plan_pending_color),
             StepStatus::InProgress => ("[~]", theme.plan_in_progress_color),
-            StepStatus::Completed => ("[x]", theme.plan_completed_color),
+            StepStatus::Completed => ("[✓]", theme.plan_completed_color),
         };
         let mut text = format!("{prefix} {}", step.text);
         if !step.elapsed.is_empty() {
@@ -557,7 +561,7 @@ fn work_panel_empty_hint(content_width: usize) -> String {
     truncate_line_to_width("No active work", content_width)
 }
 
-fn render_sidebar_work(f: &mut Frame, area: Rect, app: &App) {
+fn render_sidebar_work(f: &mut Frame, area: Rect, app: &mut App) {
     if area.height < 3 {
         return;
     }
@@ -572,10 +576,11 @@ fn render_sidebar_work(f: &mut Frame, area: Rect, app: &App) {
         app.ui_theme.mode,
     );
 
-    render_sidebar_section(f, area, "Work", lines, app);
+    let full_texts: Vec<String> = lines.iter().map(|l| spans_to_text(&l.spans)).collect();
+    render_sidebar_section(f, area, "Work", lines, full_texts, app);
 }
 
-fn render_sidebar_tasks(f: &mut Frame, area: Rect, app: &App) {
+fn render_sidebar_tasks(f: &mut Frame, area: Rect, app: &mut App) {
     if area.height < 3 {
         return;
     }
@@ -584,7 +589,8 @@ fn render_sidebar_tasks(f: &mut Frame, area: Rect, app: &App) {
     let usable_rows = area.height.saturating_sub(3) as usize;
     let lines = task_panel_lines(app, content_width.max(1), usable_rows.max(1));
 
-    render_sidebar_section(f, area, "Tasks", lines, app);
+    let full_texts: Vec<String> = lines.iter().map(|l| spans_to_text(&l.spans)).collect();
+    render_sidebar_section(f, area, "Tasks", lines, full_texts, app);
 }
 
 #[derive(Debug, Clone)]
@@ -766,7 +772,7 @@ fn active_tool_rows(app: &App) -> Vec<SidebarToolRow> {
     if !stale_running.is_empty() {
         rows.push(collapsed_stale_running_row(stale_running));
     }
-    editorial_tool_rows(rows, usize::MAX)
+    editorial_tool_rows(rows, usize::MAX, ToolRowOrder::OldestFirst)
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -833,7 +839,7 @@ fn recent_tool_rows(app: &App, limit: usize) -> Vec<SidebarToolRow> {
         .filter_map(sidebar_tool_row_from_cell)
         .take(RECENT_TOOL_SCAN_LIMIT)
         .collect();
-    editorial_tool_rows(rows, limit)
+    editorial_tool_rows(rows, limit, ToolRowOrder::NewestFirst)
 }
 
 fn push_tool_rows(
@@ -1138,7 +1144,17 @@ fn background_task_duplicates_live_tool(
         })
 }
 
-fn editorial_tool_rows(rows: Vec<SidebarToolRow>, limit: usize) -> Vec<SidebarToolRow> {
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ToolRowOrder {
+    OldestFirst,
+    NewestFirst,
+}
+
+fn editorial_tool_rows(
+    rows: Vec<SidebarToolRow>,
+    limit: usize,
+    order_mode: ToolRowOrder,
+) -> Vec<SidebarToolRow> {
     #[derive(Clone)]
     struct Candidate {
         rank: u8,
@@ -1151,9 +1167,26 @@ fn editorial_tool_rows(rows: Vec<SidebarToolRow>, limit: usize) -> Vec<SidebarTo
     let mut ci_poll_groups: Vec<(usize, SidebarToolRow, usize)> = Vec::new();
     let mut shell_wait_groups: Vec<(usize, SidebarToolRow, usize, String)> = Vec::new();
     let mut seen_success: Vec<String> = Vec::new();
+    let mut seen_success_tool_names: Vec<String> = Vec::new();
+    let mut seen_failures: Vec<String> = Vec::new();
+    let mut visible_failure_count: usize = 0;
+    const MAX_VISIBLE_FAILURES: usize = 2;
 
     for (order, mut row) in rows.into_iter().enumerate() {
         if row.status == ToolStatus::Failed {
+            // Deduplicate failures for the same tool name: keep only the most
+            // recent failure per tool. Fixes #1884 — stale failures from
+            // tools that have since succeeded no longer crowd the sidebar.
+            let fail_key = row.name.trim().to_ascii_lowercase();
+            if order_mode == ToolRowOrder::NewestFirst
+                && seen_success_tool_names.contains(&fail_key)
+            {
+                continue;
+            }
+            if seen_failures.contains(&fail_key) {
+                continue;
+            }
+            seen_failures.push(fail_key);
             row.summary = failure_summary_with_hint(&row.summary);
         }
 
@@ -1209,13 +1242,52 @@ fn editorial_tool_rows(rows: Vec<SidebarToolRow>, limit: usize) -> Vec<SidebarTo
         }
         if row.status == ToolStatus::Success {
             seen_success.push(key);
+            let normalized = row.name.trim().to_ascii_lowercase();
+            if !seen_success_tool_names.contains(&normalized) {
+                seen_success_tool_names.push(normalized.clone());
+            }
+
+            // Active rows are oldest-first, so a success means any candidate
+            // failure for the same tool is stale. Recent history rows are
+            // newest-first; in that path the success is older than any
+            // already-seen failure and must not remove it.
+            if order_mode == ToolRowOrder::OldestFirst {
+                let mut removed_visible_failures = 0usize;
+                let mut removed_any_failure = false;
+                candidates.retain(|c| {
+                    let remove = c.row.status == ToolStatus::Failed
+                        && c.row.name.trim().eq_ignore_ascii_case(&normalized);
+                    if remove {
+                        removed_any_failure = true;
+                        if c.rank == 0 {
+                            removed_visible_failures += 1;
+                        }
+                    }
+                    !remove
+                });
+                if removed_any_failure {
+                    seen_failures.retain(|seen| seen != &normalized);
+                    visible_failure_count =
+                        visible_failure_count.saturating_sub(removed_visible_failures);
+                }
+            }
         }
 
-        candidates.push(Candidate {
-            rank: tool_row_rank(&row),
-            order,
-            row,
-        });
+        // Cap visible failures at MAX_VISIBLE_FAILURES. Excess failures
+        // get demoted to rank 3 so they don't crowd the top of the
+        // sidebar. (#1884)
+        let rank = if row.status == ToolStatus::Failed {
+            if visible_failure_count >= MAX_VISIBLE_FAILURES {
+                3
+            } else {
+                visible_failure_count += 1;
+                0
+            }
+        } else {
+            tool_row_rank(&row)
+        };
+
+        candidates.push(Candidate { rank, order, row });
     }
 
     for (order, mut row, count) in ci_poll_groups {
@@ -1357,7 +1429,7 @@ fn first_nonempty_line(text: &str) -> &str {
 fn tool_status_marker(status: ToolStatus) -> (&'static str, ratatui::style::Color) {
     match status {
         ToolStatus::Running => ("[~]", palette::STATUS_WARNING),
-        ToolStatus::Success => ("[x]", palette::STATUS_SUCCESS),
+        ToolStatus::Success => ("[✓]", palette::STATUS_SUCCESS),
         ToolStatus::Failed => ("[!]", palette::STATUS_ERROR),
     }
 }
@@ -1374,7 +1446,7 @@ fn duration_ms(duration: Duration) -> u64 {
     u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
 }
 
-fn render_sidebar_subagents(f: &mut Frame, area: Rect, app: &App) {
+fn render_sidebar_subagents(f: &mut Frame, area: Rect, app: &mut App) {
     if area.height < 3 {
         return;
     }
@@ -1421,7 +1493,7 @@ fn render_sidebar_subagents(f: &mut Frame, area: Rect, app: &App) {
     let rows = sidebar_agent_rows(app);
     let lines = subagent_panel_lines(&summary, &rows, content_width, usable_rows.max(1));
 
-    render_sidebar_section(f, area, "Agents", lines, app);
+    render_sidebar_section(f, area, "Agents", lines, Vec::new(), app);
 }
 
 /// Minimal projection of the data the sub-agent sidebar needs. Lifted out
@@ -1602,6 +1674,12 @@ pub fn subagent_panel_lines(
             Style::default().fg(color),
         )));
 
+        // Auto-collapse finished sub-agents: hide detail lines for completed
+        // agents so the sidebar stays compact when work is done.
+        if row.status == "done" {
+            continue;
+        }
+
         if lines.len() >= max_rows {
             break;
         }
@@ -1646,7 +1724,7 @@ pub fn subagent_panel_lines(
 fn agent_status_marker(status: &str) -> (&'static str, ratatui::style::Color) {
     match status {
         "running" => ("[~]", palette::STATUS_WARNING),
-        "done" => ("[x]", palette::STATUS_SUCCESS),
+        "done" => ("[✓]", palette::STATUS_SUCCESS),
         "failed" => ("[!]", palette::STATUS_ERROR),
         "canceled" | "interrupted" => ("[-]", palette::TEXT_MUTED),
         _ => ("[ ]", palette::TEXT_MUTED),
@@ -1659,7 +1737,7 @@ fn agent_status_marker(status: &str) -> (&'static str, ratatui::style::Color) {
 /// cost, MCP server count, LSP toggle state, cycle count, and memory
 /// file size + mtime. Each section is a compact one-liner so the panel
 /// reads as a dashboard rather than a scrolling list.
-fn render_context_panel(f: &mut Frame, area: Rect, app: &App) {
+fn render_context_panel(f: &mut Frame, area: Rect, app: &mut App) {
     if area.height < 3 {
         return;
     }
@@ -1789,7 +1867,15 @@ fn render_context_panel(f: &mut Frame, area: Rect, app: &App) {
         )));
     }
 
-    render_sidebar_section(f, area, "Session", lines, app);
+    render_sidebar_section(f, area, "Session", lines, Vec::new(), app);
+}
+
+fn spans_to_text(spans: &[Span<'_>]) -> String {
+    let mut s = String::new();
+    for span in spans {
+        s.push_str(span.content.as_ref());
+    }
+    s
 }
 
 fn render_sidebar_section(
@@ -1797,7 +1883,8 @@ fn render_sidebar_section(
     area: Rect,
     title: &str,
     lines: Vec<Line<'static>>,
-    app: &App,
+    full_texts: Vec<String>,
+    app: &mut App,
 ) {
     if area.width < 4 || area.height < 3 {
         // Clear stale cells before bailing out (#400).
@@ -1808,6 +1895,19 @@ fn render_sidebar_section(
     }
 
     let theme = Theme::for_palette_mode(app.ui_theme.mode);
+
+    // Record hover metadata for mouse tooltip support.
+    let padding = theme.section_padding;
+    let content_area = Rect {
+        x: area.x + 1 + padding.left,
+        y: area.y + 1 + padding.top,
+        width: area.width.saturating_sub(2 + padding.left + padding.right),
+        height: area.height.saturating_sub(2 + padding.top + padding.bottom),
+    };
+    app.sidebar_hover.sections.push(SidebarHoverSection {
+        content_area,
+        lines: full_texts,
+    });
     // Truncate the panel title so it always fits within the section width
     // even after a resize. The title occupies up to 4 chars of border chrome
     // (two spaces + one space on each side), so the max title length is
@@ -1850,9 +1950,10 @@ fn render_sidebar_section(
 mod tests {
     use super::{
         ACTIVE_TOOL_COMPLETED_ROW_TTL, ACTIVE_TOOL_STALE_RUNNING_ROW_TTL, AutoSidebarPanel,
-        AutoSidebarState, SidebarAgentRow, SidebarSubagentSummary, SidebarWorkChecklistItem,
-        SidebarWorkStrategyStep, SidebarWorkSummary, auto_sidebar_panels, subagent_panel_lines,
-        task_panel_lines, work_panel_empty_hint, work_panel_lines,
+        AutoSidebarState, SidebarAgentRow, SidebarHoverSection, SidebarHoverState,
+        SidebarSubagentSummary, SidebarToolRow, SidebarWorkChecklistItem, SidebarWorkStrategyStep,
+        SidebarWorkSummary, ToolRowOrder, auto_sidebar_panels, editorial_tool_rows,
+        subagent_panel_lines, task_panel_lines, work_panel_empty_hint, work_panel_lines,
     };
     use crate::config::Config;
     use crate::palette::PaletteMode;
@@ -1892,6 +1993,15 @@ mod tests {
         App::new(options, &Config::default())
     }
 
+    fn sidebar_tool_row(name: &str, status: ToolStatus) -> SidebarToolRow {
+        SidebarToolRow {
+            name: name.to_string(),
+            status,
+            summary: String::new(),
+            duration_ms: None,
+        }
+    }
+
     fn lines_to_text(lines: &[Line<'static>]) -> Vec<String> {
         lines
             .iter()
@@ -1904,6 +2014,62 @@ mod tests {
             .collect()
     }
 
+    #[test]
+    fn editorial_rows_keep_newer_failure_when_older_success_is_seen_later() {
+        let rows = vec![
+            sidebar_tool_row("gh issue create", ToolStatus::Failed),
+            sidebar_tool_row("gh issue create", ToolStatus::Success),
+        ];
+
+        let rendered = editorial_tool_rows(rows, 4, ToolRowOrder::NewestFirst);
+
+        assert!(
+            rendered
+                .iter()
+                .any(|row| row.name == "gh issue create" && row.status == ToolStatus::Failed),
+            "newest-first rows must keep a failure newer than a later-seen success: {rendered:?}"
+        );
+    }
+
+    #[test]
+    fn editorial_rows_hide_older_failure_after_newer_success() {
+        let rows = vec![
+            sidebar_tool_row("gh issue create", ToolStatus::Success),
+            sidebar_tool_row("gh issue create", ToolStatus::Failed),
+        ];
+
+        let rendered = editorial_tool_rows(rows, 4, ToolRowOrder::NewestFirst);
+
+        assert!(
+            !rendered
+                .iter()
+                .any(|row| row.name == "gh issue create" && row.status == ToolStatus::Failed),
+            "newest-first rows should hide stale failures older than success: {rendered:?}"
+        );
+    }
+
+    #[test]
+    fn editorial_rows_reclaim_failure_slot_after_oldest_first_success() {
+        let rows = vec![
+            sidebar_tool_row("gh issue create", ToolStatus::Failed),
+            sidebar_tool_row("grep_files", ToolStatus::Failed),
+            sidebar_tool_row("gh issue create", ToolStatus::Success),
+            sidebar_tool_row("cargo test", ToolStatus::Failed),
+        ];
+
+        let rendered = editorial_tool_rows(rows, 2, ToolRowOrder::OldestFirst);
+
+        assert_eq!(
+            rendered
+                .iter()
+                .filter(|row| row.status == ToolStatus::Failed)
+                .map(|row| row.name.as_str())
+                .collect::<Vec<_>>(),
+            vec!["grep_files", "cargo test"],
+            "success should clear its stale failure and free a visible failure slot"
+        );
+    }
+
     #[test]
     fn auto_sidebar_does_not_reserve_empty_work_when_other_panels_are_active() {
         let panels = auto_sidebar_panels(AutoSidebarState {
@@ -2119,7 +2285,7 @@ mod tests {
             "recent section missing: {text:?}"
         );
         assert!(
-            text.iter().any(|line| line.contains("[x] read_file")),
+            text.iter().any(|line| line.contains("[✓] read_file")),
             "recent read_file row missing: {text:?}"
         );
     }
@@ -2148,7 +2314,7 @@ mod tests {
         let text = lines_to_text(&task_panel_lines(&app, 64, 8));
 
         assert!(
-            !text.iter().any(|line| line.contains("[x] read_file")),
+            !text.iter().any(|line| line.contains("[✓] read_file")),
             "expired completed active row should leave the sidebar: {text:?}"
         );
     }
@@ -2186,7 +2352,7 @@ mod tests {
         let text = lines_to_text(&task_panel_lines(&app, 64, 8));
 
         assert!(
-            text.iter().any(|line| line.contains("[x] read_file")),
+            text.iter().any(|line| line.contains("[✓] read_file")),
             "fresh completed active row should linger briefly: {text:?}"
         );
     }
@@ -2339,7 +2505,7 @@ mod tests {
             .expect("failed grep row should stay visible");
         let read_group_index = text
             .iter()
-            .position(|line| line.contains("[x] read_file x3"))
+            .position(|line| line.contains("[✓] read_file x3"))
             .expect("repeated read_file rows should collapse");
 
         assert!(
@@ -2348,7 +2514,7 @@ mod tests {
         );
         assert_eq!(
             text.iter()
-                .filter(|line| line.contains("[x] read_file"))
+                .filter(|line| line.contains("[✓] read_file"))
                 .count(),
             1,
             "read_file should render once after grouping: {text:?}"
@@ -2448,7 +2614,7 @@ mod tests {
 
         assert!(
             text.iter()
-                .any(|line| line.contains("[x] cargo check 1.2s")),
+                .any(|line| line.contains("[✓] cargo check 1.2s")),
             "status marker and duration should stay in the row label: {text:?}"
         );
         assert!(
@@ -2664,4 +2830,48 @@ mod tests {
             "RLM work must be visible in Agents panel: {text:?}"
         );
     }
+
+    // ---- Sidebar hover tooltip tests ----
+
+    #[test]
+    fn sidebar_hover_state_default_is_empty() {
+        let state = SidebarHoverState::default();
+        assert!(state.sections.is_empty());
+    }
+
+    #[test]
+    fn sidebar_hover_section_stores_lines() {
+        use ratatui::layout::Rect;
+        let section = SidebarHoverSection {
+            content_area: Rect::new(1, 1, 38, 8),
+            lines: vec!["line 1".to_string(), "line 2".to_string()],
+        };
+        assert_eq!(section.lines.len(), 2);
+        assert_eq!(section.lines[0], "line 1");
+        assert!(section.content_area.x > 0);
+    }
+
+    #[test]
+    fn hover_line_matching_respects_content_area_offset() {
+        use ratatui::layout::Rect;
+        let section = SidebarHoverSection {
+            content_area: Rect::new(62, 2, 36, 6),
+            lines: vec![
+                "first".to_string(),
+                "second".to_string(),
+                "third".to_string(),
+            ],
+        };
+
+        // Mouse within content area, first line
+        let line_idx = (2u16.saturating_sub(section.content_area.y)) as usize;
+        assert_eq!(section.lines[line_idx], "first");
+
+        // Mouse within content area, second line
+        let line_idx = (3u16.saturating_sub(section.content_area.y)) as usize;
+        assert_eq!(section.lines[line_idx], "second");
+
+        // Mouse outside content area (above) — row < content_area.y
+        assert!((1u16) < section.content_area.y);
+    }
 }
diff --git a/crates/tui/src/tui/theme_picker.rs b/crates/tui/src/tui/theme_picker.rs
index 85da1d41..fca7254a 100644
--- a/crates/tui/src/tui/theme_picker.rs
+++ b/crates/tui/src/tui/theme_picker.rs
@@ -317,7 +317,7 @@ mod tests {
         let mut v = ThemePickerView::new("system".to_string());
         let action = v.handle_key(key(KeyCode::Down));
         assert!(matches!(action, ViewAction::Emit(_)));
-        assert_eq!(selected_name(&action), Some(ThemeId::Whale.name()));
+        assert_eq!(selected_name(&action), Some(ThemeId::Terminal.name()));
     }
 
     #[test]
@@ -337,6 +337,7 @@ mod tests {
         v.handle_key(key(KeyCode::Down));
         v.handle_key(key(KeyCode::Down));
         v.handle_key(key(KeyCode::Down));
+        v.handle_key(key(KeyCode::Down));
         v.handle_key(key(KeyCode::Down)); // -> CatppuccinMocha
         let action = v.handle_key(key(KeyCode::Enter));
         match action {
@@ -376,8 +377,8 @@ mod tests {
     #[test]
     fn digit_jumps_to_row() {
         let mut v = ThemePickerView::new("system".to_string());
-        let action = v.handle_key(key(KeyCode::Char('5')));
-        // Row 5 (1-indexed) -> index 4 -> CatppuccinMocha
+        let action = v.handle_key(key(KeyCode::Char('6')));
+        // Row 6 (1-indexed) -> index 5 -> CatppuccinMocha
         assert_eq!(
             selected_name(&action),
             Some(ThemeId::CatppuccinMocha.name())
diff --git a/crates/tui/src/tui/transcript.rs b/crates/tui/src/tui/transcript.rs
index 9616a9c7..863e5aff 100644
--- a/crates/tui/src/tui/transcript.rs
+++ b/crates/tui/src/tui/transcript.rs
@@ -16,6 +16,7 @@
 //! Width or render-option changes still bust the entire cache (correct: wrap
 //! layout depends on width and which cells are visible at all).
 
+use std::collections::HashSet;
 use std::sync::Arc;
 
 use ratatui::{
@@ -26,6 +27,7 @@ use ratatui::{
 use crate::tui::app::TranscriptSpacing;
 use crate::tui::history::{HistoryCell, TranscriptRenderOptions};
 use crate::tui::scrolling::TranscriptLineMeta;
+use crate::tui::ui_text::CopyLineSeparator;
 
 /// Per-cell cached render output. Reused across `ensure` calls when the
 /// upstream cell's revision counter hasn't changed.
@@ -45,6 +47,12 @@ struct CachedCell {
     /// Rendered lines for this cell (without trailing inter-cell spacers),
     /// shared via `Arc` so cache enumeration is O(N) not O(N*lines).
     lines: Arc<Vec<Line<'static>>>,
+    /// Copy separators aligned with `lines`. These preserve source hard
+    /// newlines while allowing copy to remove visual soft-wrap breaks.
+    copy_separators: Arc<Vec<CopyLineSeparator>>,
+    /// Display-column widths of visual prefixes that should be omitted from
+    /// clipboard text, aligned with `lines`.
+    copy_prefix_widths: Arc<Vec<usize>>,
     /// Whether this cell's rendered output was empty (e.g. Thinking hidden).
     /// Cached so we can skip empty cells without re-rendering.
     is_empty: bool,
@@ -66,6 +74,10 @@ struct CachedCell {
 pub struct TranscriptViewCache {
     width: u16,
     options: TranscriptRenderOptions,
+    /// Snapshot of folded_thinking indices from the last `ensure` call.
+    /// When this changes, all cells must be re-rendered because the fold
+    /// state affects the rendered output but not the cell revision.
+    folded_cells: HashSet<usize>,
     /// Per-cell rendered output, indexed by current cell position.
     /// Length always equals the cell count seen on the last `ensure` call.
     per_cell: Vec<CachedCell>,
@@ -87,6 +99,7 @@ impl TranscriptViewCache {
         Self {
             width: 0,
             options: TranscriptRenderOptions::default(),
+            folded_cells: HashSet::new(),
             per_cell: Vec::new(),
             lines: Vec::new(),
             line_meta: Vec::new(),
@@ -115,33 +128,51 @@ impl TranscriptViewCache {
         width: u16,
         options: TranscriptRenderOptions,
     ) {
-        self.ensure_split(&[cells], cell_revisions, width, options);
+        self.ensure_split(
+            &[cells],
+            cell_revisions,
+            width,
+            options,
+            &HashSet::new(),
+            None,
+        );
     }
 
     /// Ensure cached lines match the provided cell shards (logically
     /// concatenated) plus per-cell revisions. Avoids the
     /// `concat-into-Vec<HistoryCell>` clone the caller would otherwise pay
     /// every frame on long transcripts.
+    ///
+    /// `folded_cells` contains original virtual indices of thinking cells
+    /// that should render in their folded (summary) form.
+    ///
+    /// `original_index_map` maps filtered (positional) indices to original
+    /// virtual indices. Required when `collapsed_cells` filtering is active
+    /// so that `folded_cells` lookups resolve to the correct original index.
     pub fn ensure_split(
         &mut self,
         cell_shards: &[&[HistoryCell]],
         cell_revisions: &[u64],
         width: u16,
         options: TranscriptRenderOptions,
+        folded_cells: &HashSet<usize>,
+        original_index_map: Option<&[usize]>,
     ) {
         let total_cells: usize = cell_shards.iter().map(|s| s.len()).sum();
 
         let layout_changed = self.width != width || self.options != options;
-        if layout_changed {
+        let folded_changed = self.folded_cells != *folded_cells;
+        if layout_changed || folded_changed {
             self.per_cell.clear();
         }
         self.width = width;
         self.options = options;
+        self.folded_cells = folded_cells.clone();
 
         // Track whether anything actually changed; if all cells are reused at
         // the same indices, we can skip the reflatten.
         let old_len = self.per_cell.len();
-        let mut any_dirty = layout_changed || old_len != total_cells;
+        let mut any_dirty = layout_changed || folded_changed || old_len != total_cells;
         let mut first_dirty: Option<usize> = if old_len != total_cells {
             Some(old_len.min(total_cells))
         } else {
@@ -183,11 +214,25 @@ impl TranscriptViewCache {
                 } else {
                     width
                 };
-                let rendered = cell.lines_with_options(render_width, options);
-                let is_empty = rendered.is_empty();
+                let original_idx = original_index_map
+                    .map(|m| *m.get(idx).unwrap_or(&idx))
+                    .unwrap_or(idx);
+                let folded = folded_cells.contains(&original_idx);
+                let rendered = cell.lines_with_copy_metadata_folded(render_width, options, folded);
+                let mut lines = Vec::with_capacity(rendered.len());
+                let mut copy_separators = Vec::with_capacity(rendered.len());
+                let mut copy_prefix_widths = Vec::with_capacity(rendered.len());
+                for rendered_line in rendered {
+                    lines.push(rendered_line.line);
+                    copy_prefix_widths.push(rendered_line.copy_prefix_width);
+                    copy_separators.push(rendered_line.copy_separator_after);
+                }
+                let is_empty = lines.is_empty();
                 new_per_cell.push(CachedCell {
                     revision: current_rev,
-                    lines: Arc::new(rendered),
+                    lines: Arc::new(lines),
+                    copy_separators: Arc::new(copy_separators),
+                    copy_prefix_widths: Arc::new(copy_prefix_widths),
                     is_empty,
                     is_stream_continuation: cell.is_stream_continuation(),
                     is_conversational: cell.is_conversational(),
@@ -280,6 +325,16 @@ impl TranscriptViewCache {
                 self.line_meta.push(TranscriptLineMeta::CellLine {
                     cell_index,
                     line_in_cell,
+                    copy_prefix_width: cached
+                        .copy_prefix_widths
+                        .get(line_in_cell)
+                        .copied()
+                        .unwrap_or(0),
+                    copy_separator_after: cached
+                        .copy_separators
+                        .get(line_in_cell)
+                        .copied()
+                        .unwrap_or(CopyLineSeparator::Newline),
                 });
             }
 
@@ -527,6 +582,7 @@ fn truncate_spans_to_width(spans: Vec<Span<'static>>, max_width: usize) -> Vec<S
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::palette;
     use crate::tui::history::{ExecCell, ExecSource, HistoryCell, ToolCell, ToolStatus};
 
     fn plain_lines(cache: &TranscriptViewCache) -> Vec<String> {
@@ -568,6 +624,20 @@ mod tests {
         }))
     }
 
+    #[test]
+    fn cache_renders_user_cells_with_highlight_background() {
+        let cells = vec![user_cell("# literal user prompt")];
+        let revisions = vec![1u64];
+
+        let mut cache = TranscriptViewCache::new();
+        cache.ensure(&cells, &revisions, 40, TranscriptRenderOptions::default());
+
+        let lines = cache.lines();
+        assert_eq!(lines[0].style.bg, Some(palette::SURFACE_ELEVATED));
+        assert_eq!(lines[0].width(), 40);
+        assert_eq!(plain_lines(&cache)[0].trim_end(), "▎ # literal user prompt");
+    }
+
     #[test]
     fn cache_reuses_cells_when_revision_unchanged() {
         let cells = vec![
@@ -979,4 +1049,116 @@ mod tests {
         );
         eprintln!("  ✓ well under 1 MB even for very long sessions");
     }
+
+    #[test]
+    fn folded_thinking_cache_invalidation() {
+        let long_content = "reasoning line\n".repeat(50);
+        let cells = [HistoryCell::Thinking {
+            content: long_content.clone(),
+            streaming: false,
+            duration_secs: Some(1.5),
+        }];
+        let revisions = [1u64];
+        let options = TranscriptRenderOptions {
+            verbose: true, // expanded by default
+            ..TranscriptRenderOptions::default()
+        };
+        let width = 80u16;
+
+        // First render: no folding → full content.
+        let mut cache = TranscriptViewCache::new();
+        cache.ensure_split(&[&cells], &revisions, width, options, &HashSet::new(), None);
+        let full_line_count = cache.total_lines();
+
+        // Second render: fold the thinking cell → should invalidate and
+        // produce fewer lines (collapsed summary).
+        let mut folded = HashSet::new();
+        folded.insert(0usize);
+        cache.ensure_split(&[&cells], &revisions, width, options, &folded, None);
+        let folded_line_count = cache.total_lines();
+
+        assert!(
+            folded_line_count < full_line_count,
+            "folded thinking should render fewer lines: folded={folded_line_count} full={full_line_count}"
+        );
+
+        // Third render: unfold → should restore full content.
+        cache.ensure_split(&[&cells], &revisions, width, options, &HashSet::new(), None);
+        let restored_line_count = cache.total_lines();
+        assert_eq!(
+            restored_line_count, full_line_count,
+            "unfolded thinking should restore full line count"
+        );
+    }
+
+    #[test]
+    fn folded_thinking_with_collapsed_cells_uses_original_indices() {
+        // Two thinking cells: cell 0 and cell 1. Cell 0 is collapsed (hidden).
+        // Fold cell 1 (original index 1). With the filtered index map,
+        // the cache should still fold the correct cell.
+        let cells = [
+            HistoryCell::Thinking {
+                content: "first thinking block\n".repeat(20),
+                streaming: false,
+                duration_secs: Some(1.0),
+            },
+            HistoryCell::Thinking {
+                content: "second thinking block\n".repeat(20),
+                streaming: false,
+                duration_secs: Some(2.0),
+            },
+        ];
+        let revisions = [1u64, 2u64];
+        let options = TranscriptRenderOptions {
+            verbose: true,
+            ..TranscriptRenderOptions::default()
+        };
+        let width = 80u16;
+
+        // No collapsing, no folding — baseline.
+        let mut cache = TranscriptViewCache::new();
+        cache.ensure_split(&[&cells], &revisions, width, options, &HashSet::new(), None);
+        let baseline = cache.total_lines();
+        assert!(baseline > 0, "baseline render should contain visible lines");
+
+        // Collapse cell 0, fold cell 1. The filtered list has only cell 1
+        // at filtered index 0, but it maps to original index 1.
+        let filtered_cells = [cells[1].clone()];
+        let filtered_revs = [2u64];
+        let index_map: Vec<usize> = vec![1]; // filtered 0 → original 1
+
+        let mut folded = HashSet::new();
+        folded.insert(1usize); // fold original index 1
+
+        let mut cache2 = TranscriptViewCache::new();
+        cache2.ensure_split(
+            &[&filtered_cells],
+            &filtered_revs,
+            width,
+            options,
+            &folded,
+            Some(&index_map),
+        );
+        let folded_filtered = cache2.total_lines();
+
+        // Cell 1 was expanded in baseline; now it should be folded.
+        // We can't compare directly to baseline because baseline had both
+        // cells, but folded_filtered should be less than if cell 1 were
+        // expanded in the filtered view.
+        let mut cache3 = TranscriptViewCache::new();
+        cache3.ensure_split(
+            &[&filtered_cells],
+            &filtered_revs,
+            width,
+            options,
+            &HashSet::new(),
+            Some(&index_map),
+        );
+        let expanded_filtered = cache3.total_lines();
+
+        assert!(
+            folded_filtered < expanded_filtered,
+            "folded cell via index map should render fewer lines: folded={folded_filtered} expanded={expanded_filtered}"
+        );
+    }
 }
diff --git a/crates/tui/src/tui/ui.rs b/crates/tui/src/tui/ui.rs
index 25e1fdb1..03cf0e39 100644
--- a/crates/tui/src/tui/ui.rs
+++ b/crates/tui/src/tui/ui.rs
@@ -9,6 +9,13 @@ use std::sync::Arc;
 use std::time::{Duration, Instant};
 
 use anyhow::Result;
+// On Windows the push/pop helpers write the escapes directly; crossterm's
+// PushKeyboardEnhancementFlags / PopKeyboardEnhancementFlags commands are
+// never referenced, so the imports are gated to avoid -D warnings failures.
+#[cfg(not(windows))]
+use crossterm::event::{
+    KeyboardEnhancementFlags, PopKeyboardEnhancementFlags, PushKeyboardEnhancementFlags,
+};
 use crossterm::{
     event::{
         self, DisableBracketedPaste, DisableFocusChange, DisableMouseCapture, EnableBracketedPaste,
@@ -17,13 +24,6 @@ use crossterm::{
     execute,
     terminal::{EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode},
 };
-// On Windows the push/pop helpers write the escapes directly; crossterm's
-// PushKeyboardEnhancementFlags / PopKeyboardEnhancementFlags commands are
-// never referenced, so the imports are gated to avoid -D warnings failures.
-#[cfg(not(windows))]
-use crossterm::event::{
-    KeyboardEnhancementFlags, PopKeyboardEnhancementFlags, PushKeyboardEnhancementFlags,
-};
 use ratatui::{
     Frame, Terminal,
     layout::{Constraint, Direction, Layout, Rect, Size},
@@ -32,13 +32,18 @@ use ratatui::{
     widgets::Block,
 };
 use tracing;
+#[cfg(target_os = "windows")]
+use windows::Win32::System::Console::{GetConsoleMode, GetStdHandle, SetConsoleMode};
 
 use crate::audit::log_sensitive_event;
 use crate::automation_manager::{AutomationManager, AutomationSchedulerConfig, spawn_scheduler};
 use crate::client::{DeepSeekClient, build_cache_warmup_request};
 use crate::commands;
 use crate::compaction::estimate_input_tokens_conservative;
-use crate::config::{ApiProvider, Config, DEFAULT_NVIDIA_NIM_BASE_URL};
+use crate::config::{
+    ApiProvider, Config, DEFAULT_NVIDIA_NIM_BASE_URL, ProviderConfig, ProvidersConfig,
+    save_provider_auth_mode_for,
+};
 use crate::config_ui::{self, ConfigUiMode, WebConfigSession, WebConfigSessionEvent};
 use crate::core::engine::{EngineConfig, EngineHandle, spawn_engine};
 use crate::core::events::Event as EngineEvent;
@@ -57,8 +62,9 @@ use crate::session_manager::{
 use crate::task_manager::{
     NewTaskRequest, SharedTaskManager, TaskManager, TaskManagerConfig, TaskStatus, TaskSummary,
 };
-use crate::tools::spec::RuntimeToolServices;
+use crate::tools::spec::{RuntimeToolServices, ToolResult};
 use crate::tools::subagent::SubAgentStatus;
+use crate::tui::app::HuntVerdict;
 use crate::tui::auto_router;
 use crate::tui::color_compat::ColorCompatBackend;
 use crate::tui::command_palette::{
@@ -103,9 +109,11 @@ use crate::tui::views::subagent_view_agents;
 use crate::tui::vim_mode;
 use crate::tui::workspace_context;
 
+use super::key_actions;
+
 use super::app::{
     App, AppAction, AppMode, OnboardingState, QueuedMessage, ReasoningEffort, SidebarFocus,
-    StatusToastLevel, SubmitDisposition, TaskPanelEntry, TuiOptions, VoiceInputState,
+    StatusToastLevel, SubmitDisposition, TaskPanelEntry, TuiOptions,
     looks_like_slash_command_input,
 };
 use super::approval::{
@@ -141,6 +149,11 @@ const UI_IDLE_POLL_MS: u64 = 48;
 const UI_ACTIVE_POLL_MS: u64 = 24;
 const WEB_CONFIG_POLL_MS: u64 = 16;
 const DISPATCH_WATCHDOG_TIMEOUT: Duration = Duration::from_secs(30);
+/// Maximum wall-clock time a turn may stay in `"in_progress"` before the UI
+/// assumes the engine stalled (e.g. sub-agent hang, lost completion event,
+/// engine panic).  Matched to [`DEFAULT_STREAM_IDLE_TIMEOUT`] so legitimate
+/// long-running tool chains are not interrupted prematurely.
+const TURN_STALL_WATCHDOG_TIMEOUT: Duration = Duration::from_secs(300);
 // Forced repaint cadence while a turn is live (model loading, compacting,
 // sub-agents running). Drives the footer water-spout animation as well as
 // the per-tool spinner pulse — keep this fast enough that the spout reads as
@@ -151,6 +164,27 @@ const DEFAULT_TERMINAL_PROBE_TIMEOUT_MS: u64 = 500;
 const PERIODIC_FULL_REPAINT_EVERY_N: u64 = 50;
 const TURN_META_PREFIX: &str = "<turn_meta>";
 const SESSION_TITLE_MAX_CHARS: usize = 32;
+const VERSION_HINT_TOAST_TTL_MS: u64 = 12_000;
+
+const REQUIRED_RELEASE_ASSETS: &[&str] = &[
+    "codewhale-artifacts-sha256.txt",
+    "codewhale-linux-arm64",
+    "codewhale-linux-arm64.tar.gz",
+    "codewhale-linux-x64",
+    "codewhale-linux-x64.tar.gz",
+    "codewhale-macos-arm64",
+    "codewhale-macos-arm64.tar.gz",
+    "codewhale-macos-x64",
+    "codewhale-macos-x64.tar.gz",
+    "codewhale-tui-linux-arm64",
+    "codewhale-tui-linux-x64",
+    "codewhale-tui-macos-arm64",
+    "codewhale-tui-macos-x64",
+    "codewhale-tui-windows-x64.exe",
+    "codewhale-windows-x64.exe",
+    "codewhale-windows-x64-portable.zip",
+    "codewhale-windows-x64.zip",
+];
 
 fn is_session_approved_for_tool(app: &App, tool_name: &str, grouping_key: &str) -> bool {
     app.approval_session_approved.contains(grouping_key)
@@ -192,10 +226,6 @@ enum TranslationEvent {
     },
 }
 
-#[derive(Debug)]
-enum VoiceInputEvent {
-    Finished { result: Result<String> },
-}
 // Reset scroll region (`\x1b[r`), origin mode (`\x1b[?6l`), and home the cursor
 // (`\x1b[H`) before letting ratatui's diff renderer repaint. The destructive
 // `\x1b[2J\x1b[3J` pair was previously appended here to also wipe the visible
@@ -279,9 +309,19 @@ pub async fn run_tui(config: &Config, options: TuiOptions) -> Result<()> {
         }
     }
 
+    #[cfg(target_os = "windows")]
+    enable_windows_ime_console_mode();
+
     let mut stdout = io::stdout();
     if use_alt_screen {
         execute!(stdout, EnterAlternateScreen)?;
+        // On Windows, stderr cannot be redirected to the log file (no dup2).
+        // Suppress verbose CLI logging once the alt-screen is active so
+        // eprintln! calls from crate::logging don't leak into the TUI buffer.
+        #[cfg(windows)]
+        crate::logging::snapshot_verbose_state();
+        #[cfg(windows)]
+        crate::logging::set_verbose(false);
     }
     // Initialize the file-backed TUI log and (on Unix) redirect raw stderr
     // away from the alt-screen for the lifetime of this guard. Any
@@ -524,6 +564,8 @@ pub async fn run_tui(config: &Config, options: TuiOptions) -> Result<()> {
         persistence_actor::init_actor(handle);
     }
 
+    submit_initial_input_if_ready(&mut app, config, &engine_handle).await?;
+
     let result = run_event_loop(
         &mut terminal,
         &mut app,
@@ -553,6 +595,8 @@ pub async fn run_tui(config: &Config, options: TuiOptions) -> Result<()> {
     disable_raw_mode()?;
     if use_alt_screen {
         execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+        #[cfg(windows)]
+        crate::logging::restore_verbose_state();
     }
     if use_mouse_capture {
         execute!(terminal.backend_mut(), DisableMouseCapture)?;
@@ -680,9 +724,14 @@ fn build_engine_config(app: &App, config: &Config) -> EngineConfig {
         notes_path: config.notes_path(),
         mcp_config_path: config.mcp_config_path(),
         skills_dir: app.skills_dir.clone(),
-        instructions: config.instructions_paths(),
+        instructions: config
+            .instructions_paths()
+            .into_iter()
+            .map(Into::into)
+            .collect(),
         project_context_pack_enabled: config.project_context_pack_enabled(),
         translation_enabled: app.translation_enabled,
+        show_thinking: app.show_thinking,
         // Effectively unlimited. V4 has a 1M context window and the user
         // wants the model running until it's actually done. The previous cap
         // of 100 hit the ceiling on long multi-step plans (wide refactors,
@@ -699,7 +748,13 @@ fn build_engine_config(app: &App, config: &Config) -> EngineConfig {
         capacity: crate::core::capacity::CapacityControllerConfig::from_app_config(config),
         todos: app.todos.clone(),
         plan_state: app.plan_state.clone(),
+        goal_state: crate::tools::goal::new_shared_goal_state_from_host(
+            app.hunt.quarry.clone(),
+            app.hunt.token_budget,
+            app.hunt.verdict == HuntVerdict::Hunted,
+        ),
         max_spawn_depth: crate::tools::subagent::DEFAULT_MAX_SPAWN_DEPTH,
+        allowed_tools: app.active_allowed_tools.clone(),
         network_policy: config.network.clone().map(|toml_cfg| {
             crate::network_policy::NetworkPolicyDecider::with_default_audit(toml_cfg.into_runtime())
         }),
@@ -715,19 +770,17 @@ fn build_engine_config(app: &App, config: &Config) -> EngineConfig {
         runtime_services: app.runtime_services.clone(),
         subagent_model_overrides: config.subagent_model_overrides(),
         subagent_api_timeout: Duration::from_secs(config.subagent_api_timeout_secs()),
+        prefer_bwrap: config.prefer_bwrap.unwrap_or(false),
         memory_enabled: config.memory_enabled(),
         memory_path: config.memory_path(),
         vision_config: config.vision_model_config(),
         strict_tool_mode: config.strict_tool_mode.unwrap_or(false),
-        goal_objective: app.goal.goal_objective.clone(),
+        goal_objective: app.hunt.quarry.clone(),
         locale_tag: app.ui_locale.tag().to_string(),
         workshop: config.workshop.clone(),
-        search_provider: config
-            .search
-            .as_ref()
-            .and_then(|s| s.provider)
-            .unwrap_or_default(),
+        search_provider: config.search_provider(),
         search_api_key: config.search.as_ref().and_then(|s| s.api_key.clone()),
+        tools_always_load: config.tools_always_load(),
     }
 }
 
@@ -867,8 +920,6 @@ async fn run_event_loop(
     let mut current_streaming_text = String::new();
     let (translation_tx, mut translation_rx) =
         tokio::sync::mpsc::unbounded_channel::<TranslationEvent>();
-    let (voice_input_tx, mut voice_input_rx) =
-        tokio::sync::mpsc::unbounded_channel::<VoiceInputEvent>();
     let mut pending_translations = 0usize;
     let mut pending_thinking_translations = 0usize;
     let mut last_queue_state = (app.queued_messages.clone(), app.queued_draft.clone());
@@ -896,7 +947,46 @@ async fn run_event_loop(
         .checked_sub(Duration::from_secs(60))
         .unwrap_or_else(Instant::now);
 
+    // Fire-and-forget version check — runs once per session in the
+    // background. On success, a short status toast advertises the update
+    // without replacing the user's configured footer/status-line chips.
+    let mut version_check: Option<tokio::task::JoinHandle<Option<String>>> = Some({
+        let current = env!("CARGO_PKG_VERSION").to_string();
+        tokio::spawn(async move {
+            let client = match reqwest::Client::builder()
+                .user_agent("codewhale-version-check")
+                .timeout(std::time::Duration::from_secs(5))
+                .build()
+            {
+                Ok(c) => c,
+                Err(_) => return None,
+            };
+            let resp = client
+                .get("https://api.github.com/repos/Hmbown/CodeWhale/releases/latest")
+                .header("Accept", "application/vnd.github+json")
+                .send()
+                .await
+                .ok()?;
+            let json: serde_json::Value = resp.json().await.ok()?;
+            version_hint_from_release_json(&json, &current)
+        })
+    });
+
     loop {
+        // Drain the version-check handle once; re-assign None so we
+        // don't poll it again.
+        let mut done = false;
+        if let Some(ref handle) = version_check {
+            done = handle.is_finished();
+        }
+        if done && let Ok(Some(hint)) = version_check.take().unwrap().await {
+            app.push_status_toast(
+                hint,
+                StatusToastLevel::Info,
+                Some(VERSION_HINT_TOAST_TTL_MS),
+            );
+        }
+
         if !drain_web_config_events(&mut web_config_session, app, config, &engine_handle).await {
             web_config_session = None;
         }
@@ -988,8 +1078,6 @@ async fn run_event_loop(
             }
         }
 
-        drain_voice_input_events(app, &mut voice_input_rx);
-
         if last_task_refresh.elapsed() >= Duration::from_millis(2500) {
             refresh_active_task_panel(app, &task_manager).await;
             last_task_refresh = Instant::now();
@@ -1277,9 +1365,7 @@ async fn run_event_loop(
                         }
                         let tool_content = match &result {
                             Ok(output) => sanitize_stream_chunk(
-                                &crate::core::engine::compact_tool_result_for_context(
-                                    &app.model, &name, output,
-                                ),
+                                &tool_result_content_for_api_message(app, &id, &name, output).await,
                             ),
                             Err(err) => sanitize_stream_chunk(&format!("Error: {err}")),
                         };
@@ -1365,6 +1451,7 @@ async fn run_event_loop(
                     } => {
                         let was_locally_cancelled = app.suppress_stream_events_until_turn_complete;
                         app.suppress_stream_events_until_turn_complete = false;
+                        app.active_allowed_tools = None;
                         if !matches!(status, crate::core::events::TurnOutcomeStatus::Completed)
                             || draws_since_last_full_repaint >= PERIODIC_FULL_REPAINT_EVERY_N
                         {
@@ -1434,6 +1521,28 @@ async fn run_event_loop(
                             .session
                             .total_conversation_tokens
                             .saturating_add(turn_tokens);
+                        app.session.total_input_tokens = app
+                            .session
+                            .total_input_tokens
+                            .saturating_add(usage.input_tokens);
+                        app.session.total_output_tokens = app
+                            .session
+                            .total_output_tokens
+                            .saturating_add(usage.output_tokens);
+                        // Only accumulate cache telemetry when reported.
+                        if let Some(hit_tokens) = usage.prompt_cache_hit_tokens {
+                            app.session.total_cache_hit_tokens = app
+                                .session
+                                .total_cache_hit_tokens
+                                .saturating_add(hit_tokens);
+                            let cache_miss = usage
+                                .prompt_cache_miss_tokens
+                                .unwrap_or_else(|| usage.input_tokens.saturating_sub(hit_tokens));
+                            app.session.total_cache_miss_tokens = app
+                                .session
+                                .total_cache_miss_tokens
+                                .saturating_add(cache_miss);
+                        }
                         app.session.last_prompt_tokens = Some(usage.input_tokens);
                         app.session.last_completion_tokens = Some(usage.output_tokens);
                         app.session.last_prompt_cache_hit_tokens = usage.prompt_cache_hit_tokens;
@@ -1492,10 +1601,35 @@ async fn run_event_loop(
                                 threshold,
                                 turn_elapsed,
                             );
+                            crate::tui::notifications::clear_taskbar_progress();
+                            crate::tui::notifications::stop_title_animation();
                         }
 
                         // Generate post-turn receipt for completed turns.
+                        // Also push a persistent status toast so users always
+                        // see the outcome in the footer (not just the 8-second
+                        // composer receipt), regardless of notification method
+                        // or platform.
                         if status == crate::core::events::TurnOutcomeStatus::Completed {
+                            // SlopLedger completion-gate: after every completed
+                            // turn, check whether there are unresolved slop entries
+                            // the agent should address before claiming the task is
+                            // done (#2127). This runs autonomously — no tool call
+                            // required — so the agent can't forget to check.
+                            if let Ok(ledger) = crate::slop_ledger::SlopLedger::load()
+                                && ledger.has_open_entries()
+                            {
+                                if let Some(gate_msg) = ledger.completion_gate_summary() {
+                                    let short =
+                                        gate_msg.lines().nth(4).unwrap_or("review before done");
+                                    app.push_status_toast(
+                                        format!("⚠️ SlopLedger: {short}"),
+                                        crate::tui::app::StatusToastLevel::Warning,
+                                        Some(12_000),
+                                    );
+                                }
+                            }
+
                             let tool_count = app.tool_evidence.len();
                             let mut receipt = "✓ turn completed".to_string();
                             if tool_count > 0 {
@@ -1509,7 +1643,16 @@ async fn run_event_loop(
                                     let _ = write!(receipt, " · {}: {summary}", evidence.tool_name);
                                 }
                             }
-                            app.set_receipt_text(receipt);
+                            app.set_receipt_text(receipt.clone());
+                            // Mirror as a persistent status toast (10s TTL).
+                            // The footer bar visibly shows status toasts,
+                            // which is more glanceable than the composer
+                            // border receipt alone.
+                            app.push_status_toast(
+                                receipt,
+                                crate::tui::app::StatusToastLevel::Info,
+                                Some(10_000),
+                            );
                         }
 
                         // Auto-save completed turn and clear crash checkpoint.
@@ -1590,7 +1733,7 @@ async fn run_event_loop(
                         }
                         app.update_model_compaction_budget();
                         app.workspace = workspace;
-                        if (app.is_loading || app.is_compacting)
+                        if (app.is_loading || app.is_compacting || app.is_purging)
                             && let Ok(manager) = SessionManager::default_location()
                         {
                             let session = build_session_snapshot(app, &manager);
@@ -1626,6 +1769,18 @@ async fn run_event_loop(
                         app.is_compacting = false;
                         app.status_message = Some(message);
                     }
+                    EngineEvent::PurgeStarted { message } => {
+                        app.is_purging = true;
+                        app.status_message = Some(message);
+                    }
+                    EngineEvent::PurgeCompleted { message, .. } => {
+                        app.is_purging = false;
+                        app.status_message = Some(message);
+                    }
+                    EngineEvent::PurgeFailed { message } => {
+                        app.is_purging = false;
+                        app.status_message = Some(message);
+                    }
                     EngineEvent::CycleAdvanced { from, to, briefing } => {
                         // Mirror the engine-side counter on the UI app state
                         // so the sidebar / slash commands stay in sync, and
@@ -1648,10 +1803,13 @@ async fn run_event_loop(
                         description,
                         stability_pct,
                         changed,
+                        pinned_combined_hash,
                         ..
                     } => {
                         app.prefix_checks_total = app.prefix_checks_total.saturating_add(1);
                         app.prefix_stability_pct = Some(stability_pct);
+                        app.last_pinned_prefix_hash =
+                            (!pinned_combined_hash.is_empty()).then_some(pinned_combined_hash);
                         if changed {
                             app.prefix_change_count = app.prefix_change_count.saturating_add(1);
                             if !description.is_empty() {
@@ -1805,6 +1963,7 @@ async fn run_event_loop(
                         id,
                         tool_name,
                         description,
+                        input,
                         approval_key,
                         approval_grouping_key,
                     } => {
@@ -1849,19 +2008,10 @@ async fn run_event_loop(
                             app.status_message =
                                 Some(format!("Blocked tool '{tool_name}' (approval_mode=never)"));
                         } else {
-                            let tool_input = app
-                                .pending_tool_uses
-                                .iter()
-                                .find(|(tool_id, _, _)| tool_id == &id)
-                                .map(|(_, _, input)| input.clone())
-                                .unwrap_or_else(|| serde_json::json!({}));
+                            let tool_input = input;
 
-                            if tool_name == "apply_patch" {
-                                maybe_add_patch_preview(app, &tool_input);
-                            }
-
-                            // Create approval request and show overlay
-                            let request = ApprovalRequest::new(
+                            push_approval_request_view(
+                                app,
                                 &id,
                                 &tool_name,
                                 &description,
@@ -1877,8 +2027,18 @@ async fn run_event_loop(
                                     "mode": app.mode.label(),
                                 }),
                             );
-                            app.view_stack
-                                .push(ApprovalView::new_for_locale(request, app.ui_locale));
+                            if let Some((method, _, _)) =
+                                crate::tui::notifications::settings(config)
+                            {
+                                let in_tmux = std::env::var("TMUX").is_ok_and(|v| !v.is_empty());
+                                crate::tui::notifications::notify_done(
+                                    method,
+                                    in_tmux,
+                                    &format!("Approval needed: {tool_name} - {description}"),
+                                    Duration::ZERO,
+                                    Duration::ZERO,
+                                );
+                            }
                             app.status_message = Some(format!(
                                 "Approval required for '{tool_name}': {description}"
                             ));
@@ -1886,6 +2046,16 @@ async fn run_event_loop(
                     }
                     EngineEvent::UserInputRequired { id, request } => {
                         app.view_stack.push(UserInputView::new(id.clone(), request));
+                        if let Some((method, _, _)) = crate::tui::notifications::settings(config) {
+                            let in_tmux = std::env::var("TMUX").is_ok_and(|v| !v.is_empty());
+                            crate::tui::notifications::notify_done(
+                                method,
+                                in_tmux,
+                                "Action required: please respond in the terminal",
+                                Duration::ZERO,
+                                Duration::ZERO,
+                            );
+                        }
                         app.status_message = Some(
                             "Action required: answer the popup with 1-4, arrows, or Enter"
                                 .to_string(),
@@ -1941,6 +2111,18 @@ async fn run_event_loop(
                                 blocked_write,
                             );
                             app.view_stack.push(ElevationView::new(request));
+                            if let Some((method, _, _)) =
+                                crate::tui::notifications::settings(config)
+                            {
+                                let in_tmux = std::env::var("TMUX").is_ok_and(|v| !v.is_empty());
+                                crate::tui::notifications::notify_done(
+                                    method,
+                                    in_tmux,
+                                    &format!("Sandbox: {denial_reason} for '{tool_name}'"),
+                                    Duration::ZERO,
+                                    Duration::ZERO,
+                                );
+                            }
                             app.status_message =
                                 Some(format!("Sandbox blocked {tool_name}: {denial_reason}"));
                         }
@@ -2004,7 +2186,6 @@ async fn run_event_loop(
                 &task_manager,
                 &mut engine_handle,
                 &mut web_config_session,
-                voice_input_tx.clone(),
                 events,
             )
             .await?
@@ -2017,10 +2198,7 @@ async fn run_event_loop(
         if reconcile_turn_liveness(app, Instant::now(), has_running_agents) {
             app.needs_redraw = true;
         }
-        if (app.is_loading
-            || has_running_agents
-            || app.is_compacting
-            || app.voice_input_state.is_some())
+        if (app.is_loading || has_running_agents || app.is_compacting || app.is_purging)
             && last_status_frame.elapsed()
                 >= Duration::from_millis(status_animation_interval_ms(app))
         {
@@ -2082,7 +2260,7 @@ async fn run_event_loop(
         // long passage can be selected in one drag (#1163).
         tick_selection_autoscroll(app);
         let allow_workspace_context_refresh =
-            !app.is_loading && !has_running_agents && !app.is_compacting;
+            !app.is_loading && !has_running_agents && !app.is_compacting && !app.is_purging;
         workspace_context::refresh_if_needed(app, now, allow_workspace_context_refresh);
 
         // Draw is gated by the frame-rate limiter (120 FPS cap). When a
@@ -2114,15 +2292,12 @@ async fn run_event_loop(
             app.needs_redraw = false;
         }
 
-        let mut poll_timeout = if app.is_loading
-            || has_running_agents
-            || app.is_compacting
-            || app.voice_input_state.is_some()
-        {
-            Duration::from_millis(active_poll_ms(app))
-        } else {
-            Duration::from_millis(idle_poll_ms(app))
-        };
+        let mut poll_timeout =
+            if app.is_loading || has_running_agents || app.is_compacting || app.is_purging {
+                Duration::from_millis(active_poll_ms(app))
+            } else {
+                Duration::from_millis(idle_poll_ms(app))
+            };
         if let Some(until_flush) = app.paste_burst_next_flush_delay_if_enabled(now) {
             poll_timeout = poll_timeout.min(until_flush);
         }
@@ -2292,6 +2467,8 @@ async fn run_event_loop(
             if app.use_mouse_capture
                 && let Event::Mouse(mouse) = evt
             {
+                // Mouse interaction clears the ✅ completion marker.
+                crate::tui::notifications::reset_title_on_interaction();
                 if should_drop_loading_mouse_motion(app, mouse) {
                     continue;
                 }
@@ -2303,7 +2480,6 @@ async fn run_event_loop(
                     &task_manager,
                     &mut engine_handle,
                     &mut web_config_session,
-                    voice_input_tx.clone(),
                     events,
                 )
                 .await?
@@ -2313,6 +2489,9 @@ async fn run_event_loop(
                 continue;
             }
 
+            // User interaction — clear the ✅ completion marker from the title.
+            crate::tui::notifications::reset_title_on_interaction();
+
             let Event::Key(key) = evt else {
                 continue;
             };
@@ -2363,6 +2542,7 @@ async fn run_event_loop(
                     }
                     _ => {}
                 }
+                submit_initial_input_if_ready(app, config, &engine_handle).await?;
                 continue;
             }
 
@@ -2685,7 +2865,6 @@ async fn run_event_loop(
                     &task_manager,
                     &mut engine_handle,
                     &mut web_config_session,
-                    voice_input_tx.clone(),
                     events,
                 )
                 .await?
@@ -2695,47 +2874,9 @@ async fn run_event_loop(
                 continue;
             }
 
-            // File-tree navigation: intercept keys when the file-tree pane is
-            // visible so Up/Down/Enter/Esc operate on the tree rather than
-            // falling through to composer or modal handlers.
-            if app.file_tree_visible {
-                match key.code {
-                    KeyCode::Up => {
-                        if let Some(state) = app.file_tree.as_mut() {
-                            state.cursor_up();
-                        }
-                        app.needs_redraw = true;
-                        continue;
-                    }
-                    KeyCode::Down => {
-                        if let Some(state) = app.file_tree.as_mut() {
-                            state.cursor_down();
-                        }
-                        app.needs_redraw = true;
-                        continue;
-                    }
-                    KeyCode::Enter => {
-                        if let Some(state) = app.file_tree.as_mut() {
-                            if let Some(rel_path) = state.activate() {
-                                // Insert @path into the composer.
-                                let path_str = rel_path.to_string_lossy().to_string();
-                                app.status_message = Some(format!("Attached @{path_str}"));
-                                app.insert_str(&format!("@{path_str} "));
-                            } else {
-                                // Directory was expanded/collapsed; rebuild.
-                                app.needs_redraw = true;
-                            }
-                        }
-                        continue;
-                    }
-                    KeyCode::Esc => {
-                        app.file_tree = None;
-                        app.status_message = Some("File tree closed".to_string());
-                        app.needs_redraw = true;
-                        continue;
-                    }
-                    _ => {}
-                }
+            // File-tree navigation: delegated to key_actions module.
+            if key_actions::handle_file_tree_key(app, &key) {
+                continue;
             }
 
             if app.is_history_search_active() {
@@ -2833,18 +2974,32 @@ async fn run_event_loop(
                 {
                     continue;
                 }
-                // Space toggles collapse/expand of the focused thinking block
-                // when the composer is empty (#1972).
+                // Space toggles fold/unfold of the focused thinking block
+                // when the composer is empty. For thinking cells, toggles
+                // between summary and full content; for other cells, toggles
+                // visibility (#1972, #2348).
                 KeyCode::Char(' ')
                     if key.modifiers == KeyModifiers::NONE && app.input.is_empty() =>
                 {
                     if let Some(idx) = detail_target_cell_index(app) {
-                        if app.collapsed_cells.contains(&idx) {
+                        let is_thinking = app
+                            .history
+                            .get(idx)
+                            .is_some_and(|c| matches!(c, HistoryCell::Thinking { .. }));
+                        if is_thinking {
+                            if app.folded_thinking.contains(&idx) {
+                                app.folded_thinking.remove(&idx);
+                                app.status_message = Some("Thinking block expanded".to_string());
+                            } else {
+                                app.folded_thinking.insert(idx);
+                                app.status_message = Some("Thinking block folded".to_string());
+                            }
+                        } else if app.collapsed_cells.contains(&idx) {
                             app.collapsed_cells.remove(&idx);
-                            app.status_message = Some("Thinking block expanded".to_string());
+                            app.status_message = Some("Cell expanded".to_string());
                         } else {
                             app.collapsed_cells.insert(idx);
-                            app.status_message = Some("Thinking block collapsed".to_string());
+                            app.status_message = Some("Cell collapsed".to_string());
                         }
                         app.mark_history_updated();
                         app.needs_redraw = true;
@@ -2930,7 +3085,21 @@ async fn run_event_loop(
                 KeyCode::Char('c') | KeyCode::Char('C')
                     if key_shortcuts::is_copy_shortcut(&key) =>
                 {
-                    copy_active_selection(app);
+                    let sel = app.selected_text();
+                    if !sel.is_empty() {
+                        if app.clipboard.write_text(&sel).is_ok() {
+                            app.push_status_toast(
+                                "Copied to clipboard",
+                                StatusToastLevel::Info,
+                                None,
+                            );
+                            app.clear_selection();
+                        } else {
+                            app.push_status_toast("Copy failed", StatusToastLevel::Error, None);
+                        }
+                    } else {
+                        copy_active_selection(app);
+                    }
                 }
                 KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                     // Four behaviors layered on Ctrl+C in priority order — see
@@ -3443,16 +3612,32 @@ async fn run_event_loop(
                     app.delete_char_forward();
                 }
                 KeyCode::Delete => {}
+                KeyCode::Left if key.modifiers.contains(KeyModifiers::SHIFT) => {
+                    if app.selection_anchor.is_none() {
+                        app.selection_anchor = Some(app.cursor_position);
+                    }
+                    app.move_cursor_left();
+                }
                 KeyCode::Left if is_word_cursor_modifier(key.modifiers) => {
+                    app.clear_selection();
                     app.move_cursor_word_backward();
                 }
                 KeyCode::Left => {
+                    app.clear_selection();
                     app.move_cursor_left();
                 }
+                KeyCode::Right if key.modifiers.contains(KeyModifiers::SHIFT) => {
+                    if app.selection_anchor.is_none() {
+                        app.selection_anchor = Some(app.cursor_position);
+                    }
+                    app.move_cursor_right();
+                }
                 KeyCode::Right if is_word_cursor_modifier(key.modifiers) => {
+                    app.clear_selection();
                     app.move_cursor_word_forward();
                 }
                 KeyCode::Right => {
+                    app.clear_selection();
                     app.move_cursor_right();
                 }
                 KeyCode::Home if key.modifiers.contains(KeyModifiers::CONTROL) => {
@@ -3468,15 +3653,19 @@ async fn run_event_loop(
                 KeyCode::Home | KeyCode::Char('a')
                     if key.modifiers.contains(KeyModifiers::CONTROL) =>
                 {
+                    app.clear_selection();
                     app.move_cursor_start();
                 }
                 KeyCode::Home => {
+                    app.clear_selection();
                     app.move_cursor_line_start();
                 }
                 KeyCode::End => {
+                    app.clear_selection();
                     app.move_cursor_line_end();
                 }
                 KeyCode::Char('e') if key.modifiers.contains(KeyModifiers::CONTROL) => {
+                    app.clear_selection();
                     app.move_cursor_end();
                 }
                 KeyCode::Char('o') if key.modifiers.contains(KeyModifiers::CONTROL) => {
@@ -3579,12 +3768,22 @@ async fn run_event_loop(
                     }
                 }
                 KeyCode::Char('x') if key.modifiers.contains(KeyModifiers::CONTROL) => {
-                    let new_mode = match app.mode {
-                        AppMode::Plan => AppMode::Agent,
-                        AppMode::Agent => AppMode::Yolo,
-                        AppMode::Yolo => AppMode::Plan,
-                    };
-                    app.set_mode(new_mode);
+                    let sel = app.selected_text();
+                    if !sel.is_empty() {
+                        if app.clipboard.write_text(&sel).is_ok() {
+                            app.push_status_toast("Cut to clipboard", StatusToastLevel::Info, None);
+                            app.delete_selection();
+                        } else {
+                            app.push_status_toast("Cut failed", StatusToastLevel::Error, None);
+                        }
+                    } else {
+                        let new_mode = match app.mode {
+                            AppMode::Plan => AppMode::Agent,
+                            AppMode::Agent => AppMode::Yolo,
+                            AppMode::Yolo => AppMode::Plan,
+                        };
+                        app.set_mode(new_mode);
+                    }
                 }
                 _ if key_shortcuts::is_paste_shortcut(&key) => {
                     app.paste_from_clipboard();
@@ -3648,7 +3847,7 @@ async fn run_event_loop(
             }
 
             if !is_plain_char && !is_enter {
-                app.paste_burst.clear_window_after_non_char();
+                app.paste_burst.deactivate_keep_window();
             }
         }
     }
@@ -3780,6 +3979,7 @@ fn reconcile_turn_liveness(app: &mut App, now: Instant, has_running_agents: bool
         && app.runtime_turn_status.is_none()
         && !has_running_agents
         && !app.is_compacting
+        && !app.is_purging
         && app.dispatch_started_at.is_some_and(|started| {
             now.saturating_duration_since(started) > DISPATCH_WATCHDOG_TIMEOUT
         })
@@ -3801,6 +4001,7 @@ fn reconcile_turn_liveness(app: &mut App, now: Instant, has_running_agents: bool
         )
         && !has_running_agents
         && !app.is_compacting
+        && !app.is_purging
     {
         app.is_loading = false;
         app.dispatch_started_at = None;
@@ -3812,6 +4013,40 @@ fn reconcile_turn_liveness(app: &mut App, now: Instant, has_running_agents: bool
         return true;
     }
 
+    // Branch 3: turn started but never completed — engine may have
+    // panicked, sub-agent may be stuck, or the completion event was lost.
+    if app.is_loading
+        && matches!(app.runtime_turn_status.as_deref(), Some("in_progress"))
+        && !has_running_agents
+        && !app.is_compacting
+        && app.turn_started_at.is_some_and(|started| {
+            now.saturating_duration_since(started) > TURN_STALL_WATCHDOG_TIMEOUT
+        })
+    {
+        // Finalize in-flight thinking / assistant / tool cells so the
+        // transcript doesn't show permanent spinners after recovery.
+        streaming_thinking::finalize_current(app);
+        app.finalize_streaming_assistant_as_interrupted();
+        app.finalize_active_cell_as_interrupted();
+        app.streaming_state.reset();
+        app.streaming_message_index = None;
+        app.streaming_thinking_active_entry = None;
+
+        app.is_loading = false;
+        app.turn_started_at = None;
+        app.runtime_turn_status = None;
+        app.runtime_turn_id = None;
+        app.dispatch_started_at = None;
+        // Per-turn scroll lock — clear so the next turn auto-scrolls.
+        app.user_scrolled_during_stream = false;
+        app.push_status_toast(
+            "Turn stalled — no completion signal received. Please try again.",
+            StatusToastLevel::Error,
+            None,
+        );
+        return true;
+    }
+
     false
 }
 
@@ -3990,6 +4225,83 @@ fn push_assistant_message(
     }
 }
 
+async fn tool_result_content_for_api_message(
+    app: &App,
+    id: &str,
+    name: &str,
+    output: &ToolResult,
+) -> String {
+    let raw = output.content.trim();
+    if raw.is_empty() {
+        return String::new();
+    }
+
+    if raw.chars().count() > crate::tool_output_receipts::RAW_TOOL_OUTPUT_RECEIPT_THRESHOLD_CHARS {
+        let messages = live_tool_receipt_messages(app, id, raw, output.success);
+        let artifacts = app.session_artifacts.clone();
+        let raw = raw.to_string();
+        match tokio::task::spawn_blocking(move || {
+            compact_live_tool_receipt(messages, artifacts, raw)
+        })
+        .await
+        {
+            Ok(Some(receipt)) => return receipt,
+            Ok(None) => {}
+            Err(err) => {
+                crate::logging::warn(format!("live tool-output receipt compaction failed: {err}"));
+            }
+        }
+    }
+
+    crate::core::engine::compact_tool_result_for_context(&app.model, name, output)
+}
+
+fn live_tool_receipt_messages(app: &App, id: &str, raw: &str, success: bool) -> Vec<Message> {
+    let mut messages = Vec::with_capacity(2);
+    if let Some(tool_use_msg) = app.api_messages.iter().rev().find(|message| {
+        message.content.iter().any(|block| {
+            matches!(block, ContentBlock::ToolUse { id: tool_use_id, .. } if tool_use_id == id)
+        })
+    }) {
+        messages.push(tool_use_msg.clone());
+    }
+    messages.push(Message {
+        role: "user".to_string(),
+        content: vec![ContentBlock::ToolResult {
+            tool_use_id: id.to_string(),
+            content: raw.to_string(),
+            is_error: Some(!success),
+            content_blocks: None,
+        }],
+    });
+    messages
+}
+
+fn compact_live_tool_receipt(
+    messages: Vec<Message>,
+    artifacts: Vec<crate::artifacts::ArtifactRecord>,
+    raw: String,
+) -> Option<String> {
+    let (compacted, _) =
+        crate::tool_output_receipts::compact_messages_for_persistence(&messages, &artifacts);
+    let content = compacted
+        .last()
+        .and_then(|message| message.content.first())
+        .and_then(|block| match block {
+            ContentBlock::ToolResult { content, .. } => Some(content),
+            _ => None,
+        })?;
+    if content != &raw && live_tool_content_is_receipt(content) {
+        Some(content.clone())
+    } else {
+        None
+    }
+}
+
+fn live_tool_content_is_receipt(content: &str) -> bool {
+    content.trim_start().starts_with("[TOOL_OUTPUT_RECEIPT]")
+}
+
 fn replace_matching_assistant_text(
     app: &mut App,
     original_text: &str,
@@ -4018,6 +4330,35 @@ fn build_queued_message(app: &mut App, input: String) -> QueuedMessage {
     QueuedMessage::new(input, skill_instruction)
 }
 
+const INITIAL_PROMPT_DEFERRED_STATUS: &str = "Initial prompt ready; complete setup to send it";
+
+async fn submit_initial_input_if_ready(
+    app: &mut App,
+    config: &Config,
+    engine_handle: &EngineHandle,
+) -> Result<()> {
+    if !app.auto_submit_initial_input {
+        return Ok(());
+    }
+
+    if app.onboarding != OnboardingState::None {
+        if app.status_message.is_none() && !app.input.trim().is_empty() {
+            app.status_message = Some(INITIAL_PROMPT_DEFERRED_STATUS.to_string());
+        }
+        return Ok(());
+    }
+
+    app.auto_submit_initial_input = false;
+    if let Some(input) = app.submit_input() {
+        if app.status_message.as_deref() == Some(INITIAL_PROMPT_DEFERRED_STATUS) {
+            app.status_message = None;
+        }
+        let queued = build_queued_message(app, input);
+        dispatch_user_message(app, config, engine_handle, queued).await?;
+    }
+    Ok(())
+}
+
 fn queue_current_draft_for_next_turn(app: &mut App) -> bool {
     let Some(input) = app.submit_input() else {
         return false;
@@ -4103,11 +4444,12 @@ async fn dispatch_user_message(
             None,
             prompts::PromptSessionContext {
                 user_memory_block: None,
-                goal_objective: app.goal.goal_objective.as_deref(),
+                goal_objective: app.hunt.quarry.as_deref(),
                 project_context_pack_enabled: config.project_context_pack_enabled(),
                 locale_tag: app.ui_locale.tag(),
                 translation_enabled: app.translation_enabled,
                 model_id: &app.model,
+                show_thinking: app.show_thinking,
             },
         ),
     );
@@ -4195,7 +4537,7 @@ async fn dispatch_user_message(
             content,
             mode: app.mode,
             model: effective_model,
-            goal_objective: app.goal.goal_objective.clone(),
+            goal_objective: app.hunt.quarry.clone(),
             reasoning_effort: effective_reasoning_effort,
             reasoning_effort_auto: auto_controls_reasoning,
             auto_model: app.auto_model,
@@ -4204,6 +4546,8 @@ async fn dispatch_user_message(
             auto_approve: app.mode == AppMode::Yolo,
             approval_mode: app.approval_mode,
             translation_enabled: app.translation_enabled,
+            show_thinking: app.show_thinking,
+            allowed_tools: app.active_allowed_tools.clone(),
         })
         .await
     {
@@ -4812,6 +5156,10 @@ async fn apply_command_result(
                 app.status_message = Some("Compacting context...".to_string());
                 let _ = engine_handle.send(Op::CompactContext).await;
             }
+            AppAction::PurgeContext => {
+                app.status_message = Some("Agent purging context...".to_string());
+                let _ = engine_handle.send(Op::PurgeContext).await;
+            }
             AppAction::TaskAdd { prompt } => {
                 let request = NewTaskRequest {
                     prompt: prompt.clone(),
@@ -5102,12 +5450,16 @@ async fn handle_mcp_ui_action(
             args,
         } => {
             changed = true;
-            mcp::add_server_config(&path, name.clone(), Some(command), None, args)
+            mcp::add_server_config(&path, name.clone(), Some(command), None, args, None)
                 .map(|()| message = Some(format!("Added MCP stdio server '{name}'")))
         }
-        crate::tui::app::McpUiAction::AddHttp { name, url } => {
+        crate::tui::app::McpUiAction::AddHttp {
+            name,
+            url,
+            transport,
+        } => {
             changed = true;
-            mcp::add_server_config(&path, name.clone(), None, Some(url), Vec::new())
+            mcp::add_server_config(&path, name.clone(), None, Some(url), Vec::new(), transport)
                 .map(|()| message = Some(format!("Added MCP HTTP/SSE server '{name}'")))
         }
         crate::tui::app::McpUiAction::Enable { name } => {
@@ -5288,82 +5640,6 @@ async fn execute_command_input(
     .await
 }
 
-fn start_voice_input(
-    app: &mut App,
-    voice_input_tx: tokio::sync::mpsc::UnboundedSender<VoiceInputEvent>,
-) {
-    if app.voice_input_state.is_some() {
-        app.status_message = Some("Voice input is already listening".to_string());
-        app.needs_redraw = true;
-        return;
-    }
-
-    let settings = match crate::settings::Settings::load() {
-        Ok(settings) => settings,
-        Err(err) => {
-            app.add_message(HistoryCell::System {
-                content: format!("Voice input unavailable: failed to load settings: {err}"),
-            });
-            app.status_message = Some("Voice input unavailable".to_string());
-            return;
-        }
-    };
-
-    let Some(command_line) = settings.voice_input_command.clone() else {
-        app.add_message(HistoryCell::System {
-            content: "Voice input is not configured. Set `voice_input_command` in settings.toml or export `DEEPSEEK_VOICE_INPUT_COMMAND`. Open the command palette and choose Voice input after configuring it. The command must write the transcript to stdout.".to_string(),
-        });
-        app.status_message = Some("Voice input not configured".to_string());
-        return;
-    };
-
-    let timeout_secs = settings.voice_input_timeout_secs;
-    let workspace = app.workspace.clone();
-    app.voice_input_state = Some(VoiceInputState::new(Instant::now()));
-    app.status_message =
-        Some("Voice input listening - transcript will appear in the composer".to_string());
-    app.needs_redraw = true;
-
-    tokio::spawn(async move {
-        let result = crate::tui::voice_input::run_configured_voice_command(
-            &command_line,
-            timeout_secs,
-            &workspace,
-        )
-        .await;
-        let _ = voice_input_tx.send(VoiceInputEvent::Finished { result });
-    });
-}
-
-fn drain_voice_input_events(
-    app: &mut App,
-    voice_input_rx: &mut tokio::sync::mpsc::UnboundedReceiver<VoiceInputEvent>,
-) {
-    while let Ok(event) = voice_input_rx.try_recv() {
-        match event {
-            VoiceInputEvent::Finished { result } => {
-                app.voice_input_state = None;
-                match result {
-                    Ok(transcript) => {
-                        let char_count = transcript.chars().count();
-                        app.insert_str(&transcript);
-                        app.status_message = Some(format!(
-                            "Voice transcript inserted ({char_count} chars) - edit, then Enter to send"
-                        ));
-                    }
-                    Err(err) => {
-                        app.add_message(HistoryCell::System {
-                            content: format!("Voice input failed: {err}"),
-                        });
-                        app.status_message = Some("Voice input failed".to_string());
-                    }
-                }
-                app.needs_redraw = true;
-            }
-        }
-    }
-}
-
 async fn steer_user_message(
     app: &mut App,
     engine_handle: &EngineHandle,
@@ -5381,6 +5657,11 @@ async fn steer_user_message(
     engine_handle.steer(content.clone()).await?;
     app.last_submitted_prompt = Some(message.display.clone());
 
+    // Flush any streaming thinking/tool content into history before
+    // inserting the steer message, so the steer appears after (below)
+    // the content that chronologically preceded it.
+    app.flush_active_cell();
+
     // Mirror steer input in local transcript/session state.
     app.add_message(HistoryCell::User {
         content: format!("+ {}", message.display),
@@ -5664,7 +5945,6 @@ fn render(f: &mut Frame, app: &mut App) {
 
     let header_height = 1;
     let footer_height = 1;
-    let body_height = size.height.saturating_sub(header_height + footer_height);
     let slash_menu_entries = visible_slash_menu_entries(app, SLASH_MENU_LIMIT);
     let mention_menu_entries =
         crate::tui::file_mention::visible_mention_menu_entries(app, MENTION_MENU_LIMIT);
@@ -5672,8 +5952,24 @@ fn render(f: &mut Frame, app: &mut App) {
         app.mention_menu_selected = mention_menu_entries.len().saturating_sub(1);
     }
     let context_usage = context_usage_snapshot(app);
+
+    // Defensive two-pass layout: pin the header to the absolute top row,
+    // then split the remaining body area for chat / preview / composer /
+    // footer. This guarantees the header is never vertically centered
+    // regardless of ratatui Flex defaults or terminal size.
+    // Fixes #1834 — macOS terminal title centering.
+    let (header_area, body_area) = {
+        let split = Layout::default()
+            .direction(Direction::Vertical)
+            .flex(ratatui::layout::Flex::Start)
+            .constraints([Constraint::Length(header_height), Constraint::Min(1)])
+            .split(size);
+        (split[0], split[1])
+    };
+
+    let body_height = body_area.height;
     let composer_max_height = body_height
-        .saturating_sub(MIN_CHAT_HEIGHT)
+        .saturating_sub(MIN_CHAT_HEIGHT + footer_height)
         .max(MIN_COMPOSER_HEIGHT);
     let composer_height = {
         let composer_widget = ComposerWidget::new(
@@ -5692,16 +5988,16 @@ fn render(f: &mut Frame, app: &mut App) {
     let pending_preview = build_pending_input_preview(app);
     let preview_height = pending_preview.desired_height(size.width);
 
-    let chunks = Layout::default()
+    let body_chunks = Layout::default()
         .direction(Direction::Vertical)
+        .flex(ratatui::layout::Flex::Start)
         .constraints([
-            Constraint::Length(header_height),   // Header
             Constraint::Min(1),                  // Chat area
             Constraint::Length(preview_height),  // Pending input preview (0 if empty)
             Constraint::Length(composer_height), // Composer
             Constraint::Length(footer_height),   // Footer
         ])
-        .split(size);
+        .split(body_area);
 
     // Render header
     {
@@ -5727,9 +6023,12 @@ fn render(f: &mut Frame, app: &mut App) {
             crate::config::ApiProvider::Openai => Some("OpenAI"),
             crate::config::ApiProvider::Atlascloud => Some("Atlas"),
             crate::config::ApiProvider::WanjieArk => Some("Wanjie"),
+            crate::config::ApiProvider::Volcengine => Some("Volc"),
             crate::config::ApiProvider::Openrouter => Some("OR"),
+            crate::config::ApiProvider::XiaomiMimo => Some("MiMo"),
             crate::config::ApiProvider::Novita => Some("Novita"),
             crate::config::ApiProvider::Fireworks => Some("Fireworks"),
+            crate::config::ApiProvider::Moonshot => Some("Kimi"),
             crate::config::ApiProvider::Sglang => Some("SGLang"),
             crate::config::ApiProvider::Vllm => Some("vLLM"),
             crate::config::ApiProvider::Ollama => Some("Ollama"),
@@ -5760,7 +6059,7 @@ fn render(f: &mut Frame, app: &mut App) {
         ));
         let header_widget = HeaderWidget::new(header_data);
         let buf = f.buffer_mut();
-        header_widget.render(chunks[0], buf);
+        header_widget.render(header_area, buf);
     }
 
     // Render chat + sidebar + optional file-tree pane
@@ -5771,19 +6070,19 @@ fn render(f: &mut Frame, app: &mut App) {
         // resize) don't retain stale content from a previous frame.
         Block::default()
             .style(Style::default().bg(app.ui_theme.surface_bg))
-            .render(chunks[1], f.buffer_mut());
+            .render(body_chunks[0], f.buffer_mut());
 
         let mut sidebar_area = None;
 
         // When the file-tree pane is visible and the terminal is wide
         // enough, reserve the left ~25% for the file tree.
         let mut chat_area =
-            if app.file_tree.is_some() && chunks[1].width >= SIDEBAR_VISIBLE_MIN_WIDTH {
+            if app.file_tree.is_some() && body_chunks[0].width >= SIDEBAR_VISIBLE_MIN_WIDTH {
                 app.file_tree_visible = true;
                 let split = Layout::default()
                     .direction(Direction::Horizontal)
                     .constraints([Constraint::Percentage(25), Constraint::Percentage(75)])
-                    .split(chunks[1]);
+                    .split(body_chunks[0]);
                 let tree_area = split[0];
                 let remaining = split[1];
 
@@ -5795,7 +6094,7 @@ fn render(f: &mut Frame, app: &mut App) {
                 remaining
             } else {
                 app.file_tree_visible = false;
-                chunks[1]
+                body_chunks[0]
             };
 
         if let Some(sidebar_width) = sidebar_width_for_chat_area(app, chat_area.width) {
@@ -5813,13 +6112,41 @@ fn render(f: &mut Frame, app: &mut App) {
 
         if let Some(sidebar_area) = sidebar_area {
             super::sidebar::render_sidebar(f, sidebar_area, app);
+
+            // Render sidebar hover tooltip if active.
+            if let Some(ref tooltip_text) = app.sidebar_hover_tooltip
+                && let Some((mouse_col, mouse_row)) = app.last_mouse_pos
+            {
+                let text_width = (tooltip_text.len() as u16).clamp(10, 60);
+                let tooltip_height = 1u16;
+                let x = mouse_col
+                    .saturating_add(2)
+                    .min(size.width.saturating_sub(text_width));
+                let y = mouse_row
+                    .saturating_sub(1)
+                    .min(size.height.saturating_sub(tooltip_height));
+                if text_width > 0 && tooltip_height > 0 {
+                    let tooltip_area = Rect {
+                        x,
+                        y,
+                        width: text_width,
+                        height: tooltip_height,
+                    };
+                    let tooltip = ratatui::widgets::Paragraph::new(tooltip_text.as_str()).style(
+                        Style::default()
+                            .bg(palette::STATUS_WARNING)
+                            .fg(palette::TEXT_MUTED),
+                    );
+                    f.render_widget(tooltip, tooltip_area);
+                }
+            }
         }
     }
 
     // Render pending-input preview (queued/steered messages, if any).
     if preview_height > 0 {
         let buf = f.buffer_mut();
-        pending_preview.render(chunks[2], buf);
+        pending_preview.render(body_chunks[1], buf);
     }
 
     // Render composer
@@ -5831,19 +6158,60 @@ fn render(f: &mut Frame, app: &mut App) {
             &mention_menu_entries,
         );
         let buf = f.buffer_mut();
-        composer_widget.render(chunks[3], buf);
-        composer_widget.cursor_pos(chunks[3])
+        composer_widget.render(body_chunks[2], buf);
+        composer_widget.cursor_pos(body_chunks[2])
     };
+    app.viewport.last_composer_area = Some(body_chunks[2]);
+    {
+        let area = body_chunks[2];
+        let has_panel = app.composer_border && area.height >= 3 && area.width >= 12;
+        let inner = if has_panel {
+            ratatui::widgets::Block::default()
+                .borders(ratatui::widgets::Borders::ALL)
+                .inner(area)
+        } else {
+            area
+        };
+        app.viewport.last_composer_content = Some(inner);
+
+        // Compute scroll offset and top padding for mouse coordinate mapping.
+        let input_text = app.composer_display_input();
+        let input_cursor = app.composer_display_cursor();
+        let content_width = usize::from(inner.width.max(1));
+        let menu_lines = ComposerWidget::new(
+            app,
+            composer_max_height,
+            &slash_menu_entries,
+            &mention_menu_entries,
+        )
+        .active_menu_reserved_rows();
+        let budget = crate::tui::widgets::composer_input_rows_budget(inner.height, menu_lines);
+        let (_, _, _, scroll_offset) = crate::tui::widgets::layout_input_with_scroll(
+            input_text,
+            input_cursor,
+            content_width,
+            budget,
+        );
+        let visible_lines = if input_text.is_empty() {
+            1
+        } else {
+            // Count wrapped lines (approximation matching the render path).
+            crate::tui::widgets::wrap_input_lines_for_mouse(input_text, content_width).len()
+        };
+        let top_padding = budget.saturating_sub(visible_lines.clamp(1, budget));
+        app.viewport.last_composer_scroll_offset = scroll_offset;
+        app.viewport.last_composer_top_padding = top_padding;
+    }
     if let Some(cursor_pos) = cursor_pos {
         f.set_cursor_position(cursor_pos);
     }
 
     // Render footer
-    render_footer(f, chunks[4], app);
+    render_footer(f, body_chunks[3], app);
     // Toast stack overlay (#439): when multiple status toasts are queued,
     // surface the older ones as a 1-2 line strip above the footer so a
     // burst of events isn't collapsed to a single visible message.
-    render_toast_stack_overlay(f, size, chunks[3], chunks[4], app);
+    render_toast_stack_overlay(f, size, body_chunks[2], body_chunks[3], app);
 
     // Decision card overlay (v0.8.43 truth-surface). When a decision card is
     // active, render it centered on top of the transcript.
@@ -5977,7 +6345,6 @@ async fn handle_view_events(
     task_manager: &SharedTaskManager,
     engine_handle: &mut EngineHandle,
     web_config_session: &mut Option<WebConfigSession>,
-    voice_input_tx: tokio::sync::mpsc::UnboundedSender<VoiceInputEvent>,
     events: Vec<ViewEvent>,
 ) -> Result<bool> {
     for event in events {
@@ -6008,9 +6375,6 @@ async fn handle_view_events(
                 crate::tui::views::CommandPaletteAction::OpenTextPager { title, content } => {
                     open_text_pager(app, title, content);
                 }
-                crate::tui::views::CommandPaletteAction::VoiceInput => {
-                    start_voice_input(app, voice_input_tx.clone());
-                }
             },
             ViewEvent::OpenTextPager { title, content } => {
                 open_text_pager(app, title, content);
@@ -6032,31 +6396,19 @@ async fn handle_view_events(
                 approval_key,
                 approval_grouping_key,
             } => {
-                if decision == ReviewDecision::ApprovedForSession {
-                    // Store the tool name (backward compat) and the lossy
-                    // grouping key so later flag variants of the same
-                    // command family are also auto-approved (v0.8.37).
-                    app.approval_session_approved.insert(tool_name.clone());
-                    app.approval_session_approved
-                        .insert(approval_grouping_key.clone());
-                }
-
-                match decision {
-                    ReviewDecision::Approved | ReviewDecision::ApprovedForSession => {
-                        let _ = engine_handle.approve_tool_call(tool_id).await;
-                    }
-                    ReviewDecision::Denied | ReviewDecision::Abort => {
-                        // Cache the denial so the model retry-loop doesn't
-                        // re-prompt for the exact same approval_key (#360).
-                        // Only the key (per-call unique) is stored — NOT
-                        // the tool_name, which would block all future
-                        // invocations of the same tool type (#1377).
-                        if !timed_out {
-                            app.approval_session_denied.insert(approval_key);
-                        }
-                        let _ = engine_handle.deny_tool_call(tool_id).await;
-                    }
-                }
+                apply_approval_decision(
+                    app,
+                    engine_handle,
+                    ApprovalDecisionEvent {
+                        tool_id,
+                        tool_name,
+                        decision,
+                        timed_out,
+                        approval_key,
+                        approval_grouping_key,
+                    },
+                )
+                .await;
 
                 if timed_out {
                     app.add_message(HistoryCell::System {
@@ -6270,6 +6622,17 @@ async fn handle_view_events(
             ViewEvent::ProviderPickerApiKeySubmitted { provider, api_key } => {
                 apply_provider_picker_api_key(app, engine_handle, config, provider, api_key).await;
             }
+            ViewEvent::ProviderPickerKimiOAuthEnabled { provider } => {
+                apply_provider_picker_auth_mode(
+                    app,
+                    engine_handle,
+                    config,
+                    provider,
+                    "kimi_oauth",
+                    "Linked Kimi CLI OAuth",
+                )
+                .await;
+            }
             ViewEvent::ModeSelected { mode } => {
                 let msg = commands::switch_mode(app, mode);
                 app.add_message(HistoryCell::System { content: msg });
@@ -6318,6 +6681,69 @@ async fn handle_view_events(
     Ok(false)
 }
 
+fn push_approval_request_view(
+    app: &mut App,
+    id: &str,
+    tool_name: &str,
+    description: &str,
+    tool_input: &serde_json::Value,
+    approval_key: &str,
+) {
+    if tool_name == "apply_patch" {
+        maybe_add_patch_preview(app, tool_input);
+    }
+
+    let request = ApprovalRequest::new(id, tool_name, description, tool_input, approval_key);
+    app.view_stack
+        .push(ApprovalView::new_for_locale(request, app.ui_locale));
+}
+
+struct ApprovalDecisionEvent {
+    tool_id: String,
+    tool_name: String,
+    decision: ReviewDecision,
+    timed_out: bool,
+    approval_key: String,
+    approval_grouping_key: String,
+}
+
+async fn apply_approval_decision(
+    app: &mut App,
+    engine_handle: &mut EngineHandle,
+    event: ApprovalDecisionEvent,
+) {
+    if event.decision == ReviewDecision::ApprovedForSession {
+        // Store the tool name (backward compat) and the lossy grouping key so
+        // later flag variants of the same command family are also auto-approved
+        // (v0.8.37).
+        app.approval_session_approved
+            .insert(event.tool_name.clone());
+        app.approval_session_approved
+            .insert(event.approval_grouping_key.clone());
+    }
+
+    match event.decision {
+        ReviewDecision::Approved | ReviewDecision::ApprovedForSession => {
+            let _ = engine_handle.approve_tool_call(event.tool_id).await;
+        }
+        ReviewDecision::Denied => {
+            // Cache the denial so the model retry-loop doesn't re-prompt for
+            // the exact same approval_key (#360). Only the key (per-call
+            // unique) is stored — NOT the tool_name, which would block all
+            // future invocations of the same tool type (#1377).
+            if !event.timed_out {
+                app.approval_session_denied.insert(event.approval_key);
+            }
+            let _ = engine_handle.deny_tool_call(event.tool_id).await;
+        }
+        ReviewDecision::Abort => {
+            engine_handle.cancel();
+            mark_active_turn_cancelled_locally(app);
+            app.status_message = Some("Request cancelled".to_string());
+        }
+    }
+}
+
 fn mark_active_turn_cancelled_locally(app: &mut App) {
     app.is_loading = false;
     app.dispatch_started_at = None;
@@ -6477,7 +6903,7 @@ async fn apply_provider_picker_api_key(
     provider: ApiProvider,
     api_key: String,
 ) {
-    use crate::config::{ProviderConfig, ProvidersConfig, save_api_key_for};
+    use crate::config::save_api_key_for;
 
     match save_api_key_for(provider, &api_key) {
         Ok(path) => {
@@ -6516,9 +6942,12 @@ async fn apply_provider_picker_api_key(
             ApiProvider::Openai => &mut providers.openai,
             ApiProvider::Atlascloud => &mut providers.atlascloud,
             ApiProvider::WanjieArk => &mut providers.wanjie_ark,
+            ApiProvider::Volcengine => &mut providers.volcengine,
             ApiProvider::Openrouter => &mut providers.openrouter,
+            ApiProvider::XiaomiMimo => &mut providers.xiaomi_mimo,
             ApiProvider::Novita => &mut providers.novita,
             ApiProvider::Fireworks => &mut providers.fireworks,
+            ApiProvider::Moonshot => &mut providers.moonshot,
             ApiProvider::Sglang => &mut providers.sglang,
             ApiProvider::Vllm => &mut providers.vllm,
             ApiProvider::Ollama => &mut providers.ollama,
@@ -6529,6 +6958,57 @@ async fn apply_provider_picker_api_key(
     switch_provider(app, engine_handle, config, provider, None).await;
 }
 
+async fn apply_provider_picker_auth_mode(
+    app: &mut App,
+    engine_handle: &mut EngineHandle,
+    config: &mut Config,
+    provider: ApiProvider,
+    auth_mode: &str,
+    status_prefix: &str,
+) {
+    match save_provider_auth_mode_for(provider, auth_mode) {
+        Ok(path) => {
+            set_provider_auth_mode_in_memory(config, provider, auth_mode.to_string());
+            app.status_message = Some(format!("{status_prefix}; saved to {}", path.display()));
+            app.api_key_env_only = false;
+        }
+        Err(err) => {
+            app.add_message(HistoryCell::System {
+                content: format!(
+                    "Failed to save {} auth mode: {err}\nProvider unchanged.",
+                    provider.as_str()
+                ),
+            });
+            return;
+        }
+    }
+
+    switch_provider(app, engine_handle, config, provider, None).await;
+}
+
+fn set_provider_auth_mode_in_memory(config: &mut Config, provider: ApiProvider, auth_mode: String) {
+    let providers = config
+        .providers
+        .get_or_insert_with(ProvidersConfig::default);
+    let entry: &mut ProviderConfig = match provider {
+        ApiProvider::Deepseek | ApiProvider::DeepseekCN => return,
+        ApiProvider::NvidiaNim => &mut providers.nvidia_nim,
+        ApiProvider::Openai => &mut providers.openai,
+        ApiProvider::Atlascloud => &mut providers.atlascloud,
+        ApiProvider::WanjieArk => &mut providers.wanjie_ark,
+        ApiProvider::Volcengine => &mut providers.volcengine,
+        ApiProvider::Openrouter => &mut providers.openrouter,
+        ApiProvider::XiaomiMimo => &mut providers.xiaomi_mimo,
+        ApiProvider::Novita => &mut providers.novita,
+        ApiProvider::Fireworks => &mut providers.fireworks,
+        ApiProvider::Moonshot => &mut providers.moonshot,
+        ApiProvider::Sglang => &mut providers.sglang,
+        ApiProvider::Vllm => &mut providers.vllm,
+        ApiProvider::Ollama => &mut providers.ollama,
+    };
+    entry.auth_mode = Some(auth_mode);
+}
+
 fn apply_loaded_session(app: &mut App, config: &Config, session: &SavedSession) -> bool {
     let (messages, recovered_draft) = recover_interrupted_user_tail(&session.messages);
     app.api_messages = messages;
@@ -6606,7 +7086,13 @@ fn apply_loaded_session(app: &mut App, config: &Config, session: &SavedSession)
     app.session.last_prompt_cache_hit_tokens = None;
     app.session.last_prompt_cache_miss_tokens = None;
     app.session.last_reasoning_replay_tokens = None;
+    // Accumulated token breakdown is per-runtime-session; reset on load.
+    app.session.reset_token_breakdown();
     app.session.turn_cache_history.clear();
+    // Restore cumulative turn duration so the footer "worked" chip
+    // persists across session restarts (#2038).
+    app.cumulative_turn_duration =
+        std::time::Duration::from_secs(session.metadata.cumulative_turn_secs);
     app.current_session_id = Some(session.metadata.id.clone());
     app.session_artifacts = session.artifacts.clone();
     app.session_title = Some(session.metadata.title.clone());
@@ -6720,6 +7206,8 @@ fn pause_terminal(
     disable_raw_mode()?;
     if use_alt_screen {
         execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+        #[cfg(windows)]
+        crate::logging::restore_verbose_state();
     }
     if use_mouse_capture {
         execute!(terminal.backend_mut(), DisableMouseCapture)?;
@@ -6740,6 +7228,10 @@ fn resume_terminal(
     enable_raw_mode()?;
     if use_alt_screen {
         execute!(terminal.backend_mut(), EnterAlternateScreen)?;
+        // Re-entering alt-screen after mode recovery — suppress verbose
+        // CLI logging again so eprintln! doesn't leak into the TUI.
+        #[cfg(windows)]
+        crate::logging::set_verbose(false);
     }
     recover_terminal_modes(
         terminal.backend_mut(),
@@ -6855,6 +7347,36 @@ pub fn emergency_restore_terminal() {
     let _ = execute!(stdout, LeaveAlternateScreen);
 }
 
+/// On Windows, ensure the console input handle has `ENABLE_WINDOW_INPUT`
+/// (0x0008) set. crossterm's `enable_raw_mode()` removes this flag, which
+/// breaks IME composition (Chinese/Japanese/Korean input methods cannot
+/// commit characters) on some Windows configurations (e.g. Windows Terminal
+/// in conhost compatibility mode, or the legacy console with VT input).
+///
+/// Best-effort and idempotent. Silently ignored if the console handle or
+/// mode query fails.
+#[cfg(target_os = "windows")]
+fn enable_windows_ime_console_mode() {
+    use windows::Win32::System::Console::CONSOLE_MODE;
+    const ENABLE_WINDOW_INPUT: CONSOLE_MODE = CONSOLE_MODE(0x0008);
+
+    // SAFETY: Win32 console API is safe to call from any thread.
+    // Failures (console handle invalid, mode query fails) are silently
+    // ignored — this is a best-effort IME compatibility tweak.
+    unsafe {
+        let Ok(handle) = GetStdHandle(windows::Win32::System::Console::STD_INPUT_HANDLE) else {
+            return;
+        };
+        let mut mode = CONSOLE_MODE(0);
+        if GetConsoleMode(handle, &mut mode).is_err() {
+            return;
+        }
+        if mode.0 & ENABLE_WINDOW_INPUT.0 == 0 {
+            let _ = SetConsoleMode(handle, mode | ENABLE_WINDOW_INPUT);
+        }
+    }
+}
+
 /// Re-establish terminal mode flags. Idempotent and best-effort: each
 /// underlying flag is silently discarded by terminals that don't support
 /// it, and a single flag's failure doesn't prevent later flags from being
@@ -6879,6 +7401,9 @@ fn recover_terminal_modes<W: Write>(
     use_mouse_capture: bool,
     use_bracketed_paste: bool,
 ) {
+    #[cfg(target_os = "windows")]
+    enable_windows_ime_console_mode();
+
     push_keyboard_enhancement_flags(writer);
     if use_mouse_capture && let Err(err) = execute!(writer, EnableMouseCapture) {
         tracing::debug!(?err, "EnableMouseCapture ignored");
@@ -7404,8 +7929,18 @@ fn activity_detail_text(app: &App, cell_index: usize, width: u16) -> Option<Stri
         sections.push(status);
     }
 
-    if let Some((position, total)) = thinking_chunk_position(app, cell_index) {
-        sections.push(format!("Thinking chunk: {position} of {total}"));
+    let activity_indices = activity_indices(app);
+    if let Some(position) = activity_indices.iter().position(|&idx| idx == cell_index) {
+        sections.push(format!(
+            "Activity chunk: {} of {}",
+            position + 1,
+            activity_indices.len()
+        ));
+        sections.extend(activity_navigation_lines(app, position, &activity_indices));
+    }
+
+    if let Some(handle) = activity_detail_handle_line(app, cell_index, cell) {
+        sections.push(handle);
     }
 
     sections.push(String::new());
@@ -7457,6 +7992,22 @@ fn reasoning_timeline_text(app: &App, selected_cell_index: usize) -> Option<Stri
     ));
     if let Some(position) = selected_position {
         sections.push(format!("Selected chunk: {position} of {total}"));
+        if position > 1 {
+            let previous_index = thinking_indices[position - 2];
+            let preview = thinking_chunk_preview(app, previous_index);
+            sections.push(format!(
+                "Previous chunk: {} of {total} - {preview}",
+                position - 1
+            ));
+        }
+        if position < total {
+            let next_index = thinking_indices[position];
+            let preview = thinking_chunk_preview(app, next_index);
+            sections.push(format!(
+                "Next chunk: {} of {total} - {preview}",
+                position + 1
+            ));
+        }
     }
     sections.push(String::new());
 
@@ -7498,6 +8049,18 @@ fn reasoning_timeline_text(app: &App, selected_cell_index: usize) -> Option<Stri
     Some(sections.join("\n"))
 }
 
+fn thinking_chunk_preview(app: &App, cell_index: usize) -> String {
+    let Some(HistoryCell::Thinking { content, .. }) = app.cell_at_virtual_index(cell_index) else {
+        return "thinking".to_string();
+    };
+    let preview = one_line_summary(content, 64);
+    if preview.is_empty() {
+        "thinking".to_string()
+    } else {
+        preview
+    }
+}
+
 fn activity_cell_label(app: &App, cell_index: usize, cell: &HistoryCell) -> String {
     match cell {
         HistoryCell::Thinking { .. } => "thinking".to_string(),
@@ -7606,28 +8169,70 @@ fn format_activity_duration_ms(ms: u64) -> String {
     }
 }
 
-fn thinking_chunk_position(app: &App, cell_index: usize) -> Option<(usize, usize)> {
-    if !matches!(
-        app.cell_at_virtual_index(cell_index),
-        Some(HistoryCell::Thinking { .. })
-    ) {
-        return None;
-    }
+fn activity_indices(app: &App) -> Vec<usize> {
+    (0..app.virtual_cell_count())
+        .filter(|&idx| {
+            app.cell_at_virtual_index(idx)
+                .is_some_and(is_meaningful_activity_cell)
+        })
+        .collect()
+}
 
-    let mut total = 0usize;
-    let mut position = None;
-    for idx in 0..app.virtual_cell_count() {
-        if matches!(
-            app.cell_at_virtual_index(idx),
-            Some(HistoryCell::Thinking { .. })
-        ) {
-            total += 1;
-            if idx == cell_index {
-                position = Some(total);
-            }
+fn activity_navigation_lines(
+    app: &App,
+    position: usize,
+    activity_indices: &[usize],
+) -> Vec<String> {
+    let total = activity_indices.len();
+    let mut lines = Vec::new();
+    if position > 0 {
+        let previous_idx = activity_indices[position - 1];
+        if let Some(cell) = app.cell_at_virtual_index(previous_idx) {
+            let label = activity_cell_label(app, previous_idx, cell);
+            lines.push(format!(
+                "Previous activity: {} of {total} - {}",
+                position,
+                truncate_line_to_width(&label, 56)
+            ));
         }
     }
-    position.map(|pos| (pos, total))
+    if position + 1 < total {
+        let next_idx = activity_indices[position + 1];
+        if let Some(cell) = app.cell_at_virtual_index(next_idx) {
+            let label = activity_cell_label(app, next_idx, cell);
+            lines.push(format!(
+                "Next activity: {} of {total} - {}",
+                position + 2,
+                truncate_line_to_width(&label, 56)
+            ));
+        }
+    }
+    lines
+}
+
+fn activity_detail_handle_line(app: &App, cell_index: usize, cell: &HistoryCell) -> Option<String> {
+    if let Some(detail) = app.tool_detail_record_for_cell(cell_index) {
+        if let Some(artifact) = app
+            .session_artifacts
+            .iter()
+            .find(|artifact| artifact.tool_call_id == detail.tool_id)
+        {
+            return Some(format!(
+                "Detail handle: {} (retrieve_tool_result ref={}; Alt+V raw details)",
+                artifact.id, artifact.id
+            ));
+        }
+        return Some(format!(
+            "Detail handle: tool:{} (Alt+V raw details)",
+            detail.tool_id
+        ));
+    }
+
+    match cell {
+        HistoryCell::Tool(_) => Some("Detail handle: Alt+V details".to_string()),
+        HistoryCell::SubAgent(_) => Some("Detail handle: Alt+V details".to_string()),
+        _ => None,
+    }
 }
 
 fn activity_cell_to_text(cell: &HistoryCell, width: u16) -> String {
@@ -7906,5 +8511,71 @@ fn extract_reasoning_header(text: &str) -> Option<String> {
     }
 }
 
+fn version_hint_from_release_json(json: &serde_json::Value, current: &str) -> Option<String> {
+    if !release_has_required_assets(json) {
+        return None;
+    }
+
+    let tag = json["tag_name"].as_str()?;
+    let latest = tag.trim_start_matches('v');
+    if !is_newer_version(latest, current) {
+        return None;
+    }
+
+    Some(format!(
+        "v{latest} available - run `codewhale update` and restart"
+    ))
+}
+
+fn release_has_required_assets(json: &serde_json::Value) -> bool {
+    if json
+        .get("draft")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false)
+    {
+        return false;
+    }
+    if json
+        .get("prerelease")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false)
+    {
+        return false;
+    }
+
+    REQUIRED_RELEASE_ASSETS
+        .iter()
+        .all(|required| release_has_uploaded_asset(json, required))
+}
+
+fn release_has_uploaded_asset(json: &serde_json::Value, required: &str) -> bool {
+    let Some(assets) = json.get("assets").and_then(serde_json::Value::as_array) else {
+        return false;
+    };
+    assets.iter().any(|asset| {
+        asset.get("name").and_then(serde_json::Value::as_str) == Some(required)
+            && asset.get("state").and_then(serde_json::Value::as_str) == Some("uploaded")
+    })
+}
+
+fn is_newer_version(latest: &str, current: &str) -> bool {
+    // Compare semver so dev builds (e.g. "0.8.46-pre") don't trigger false
+    // hints. Falls back to string compare on unparseable versions.
+    match (parse_semver(latest), parse_semver(current)) {
+        (Some(l), Some(c)) => l > c,
+        _ => latest != current,
+    }
+}
+
+/// Parse a `major.minor.patch` version string into a comparable tuple.
+/// Returns `None` on any parse failure (non-semver, dev suffixes, etc.).
+fn parse_semver(v: &str) -> Option<(u32, u32, u32)> {
+    let mut parts = v.splitn(3, '.');
+    let major = parts.next()?.parse::<u32>().ok()?;
+    let minor = parts.next()?.parse::<u32>().ok()?;
+    let patch = parts.next().unwrap_or("0").parse::<u32>().ok()?;
+    Some((major, minor, patch))
+}
+
 #[cfg(test)]
 mod tests;
diff --git a/crates/tui/src/tui/ui/tests.rs b/crates/tui/src/tui/ui/tests.rs
index 6b983961..55258e74 100644
--- a/crates/tui/src/tui/ui/tests.rs
+++ b/crates/tui/src/tui/ui/tests.rs
@@ -1,5 +1,5 @@
 use super::*;
-use crate::config::{ApiProvider, Config};
+use crate::config::{ApiProvider, Config, DEFAULT_TEXT_MODEL};
 use crate::config_ui::{self, WebConfigSession, WebConfigSessionEvent};
 use crate::core::engine::mock_engine_handle;
 use crate::tui::active_cell::ActiveCell;
@@ -294,6 +294,21 @@ fn word_cursor_modifier_accepts_control_and_alt() {
     assert!(!is_word_cursor_modifier(KeyModifiers::SHIFT));
 }
 
+fn select_full_transcript(app: &mut App) {
+    app.viewport.transcript_selection.anchor = Some(TranscriptSelectionPoint {
+        line_index: 0,
+        column: 0,
+    });
+    app.viewport.transcript_selection.head = Some(TranscriptSelectionPoint {
+        line_index: app
+            .viewport
+            .transcript_cache
+            .total_lines()
+            .saturating_sub(1),
+        column: 80,
+    });
+}
+
 #[test]
 fn selection_point_from_position_ignores_top_padding() {
     let area = Rect {
@@ -375,6 +390,90 @@ fn selection_to_text_handles_multiline_and_reversed_endpoints() {
     assert_eq!(selection_to_text(&app).as_deref(), Some("a beta\ngam"));
 }
 
+#[test]
+fn selection_to_text_removes_visual_wrap_breaks_from_paragraphs() {
+    let mut app = create_test_app();
+    app.history = vec![HistoryCell::Assistant {
+        content: "alpha beta gamma delta epsilon".to_string(),
+        streaming: false,
+    }];
+    app.resync_history_revisions();
+    app.viewport.transcript_cache.ensure(
+        &app.history,
+        &app.history_revisions,
+        14,
+        app.transcript_render_options(),
+    );
+    select_full_transcript(&mut app);
+
+    let selected = selection_to_text(&app).expect("selection text");
+    assert!(
+        !selected.contains('\n'),
+        "soft-wrapped paragraph copied with visual newlines: {selected:?}"
+    );
+    assert!(selected.contains("alpha beta gamma delta epsilon"));
+}
+
+#[test]
+fn selection_to_text_preserves_wrapped_long_words() {
+    let mut app = create_test_app();
+    app.history = vec![HistoryCell::Assistant {
+        content: "abcdefghijklmnop".to_string(),
+        streaming: false,
+    }];
+    app.resync_history_revisions();
+    app.viewport.transcript_cache.ensure(
+        &app.history,
+        &app.history_revisions,
+        10,
+        app.transcript_render_options(),
+    );
+    select_full_transcript(&mut app);
+
+    let selected = selection_to_text(&app).expect("selection text");
+    assert_eq!(selected, "abcdefghijklmnop");
+}
+
+#[test]
+fn selection_to_text_strips_code_block_visual_wrap_prefixes() {
+    let mut app = create_test_app();
+    app.history = vec![HistoryCell::Assistant {
+        content: "```\nlet example = abcdefghijklmnop;\n```".to_string(),
+        streaming: false,
+    }];
+    app.resync_history_revisions();
+    app.viewport.transcript_cache.ensure(
+        &app.history,
+        &app.history_revisions,
+        14,
+        app.transcript_render_options(),
+    );
+    select_full_transcript(&mut app);
+
+    let selected = selection_to_text(&app).expect("selection text");
+    assert_eq!(selected, "let example = abcdefghijklmnop;");
+}
+
+#[test]
+fn selection_to_text_strips_list_continuation_prefixes() {
+    let mut app = create_test_app();
+    app.history = vec![HistoryCell::Assistant {
+        content: "- alpha beta gamma delta epsilon".to_string(),
+        streaming: false,
+    }];
+    app.resync_history_revisions();
+    app.viewport.transcript_cache.ensure(
+        &app.history,
+        &app.history_revisions,
+        14,
+        app.transcript_render_options(),
+    );
+    select_full_transcript(&mut app);
+
+    let selected = selection_to_text(&app).expect("selection text");
+    assert_eq!(selected, "- alpha beta gamma delta epsilon");
+}
+
 #[test]
 fn selection_to_text_copies_rendered_transcript_block() {
     let mut app = create_test_app();
@@ -1260,6 +1359,96 @@ fn create_test_options() -> TuiOptions {
     }
 }
 
+#[tokio::test]
+async fn tool_result_api_content_receipts_large_live_output() {
+    let _guard = crate::tools::truncate::TEST_SPILLOVER_GUARD
+        .lock()
+        .unwrap_or_else(|err| err.into_inner());
+    let tmp = TempDir::new().expect("spillover tempdir");
+    let prior = crate::tools::truncate::set_test_spillover_root(Some(
+        tmp.path().join(".deepseek").join("tool_outputs"),
+    ));
+    struct Restore(Option<PathBuf>);
+    impl Drop for Restore {
+        fn drop(&mut self) {
+            crate::tools::truncate::set_test_spillover_root(self.0.take());
+        }
+    }
+    let _restore = Restore(prior);
+
+    let mut app = App::new(create_test_options(), &Config::default());
+    app.api_messages.push(Message {
+        role: "assistant".to_string(),
+        content: vec![ContentBlock::ToolUse {
+            id: "call-live-big".to_string(),
+            name: "exec_shell".to_string(),
+            input: serde_json::json!({"command": "cargo test"}),
+            caller: None,
+        }],
+    });
+
+    let raw = "LIVE_RAW_SENTINEL\n".repeat(900);
+    let output = crate::tools::spec::ToolResult::success(raw.clone());
+    let content =
+        tool_result_content_for_api_message(&app, "call-live-big", "exec_shell", &output).await;
+
+    assert!(content.contains("[TOOL_OUTPUT_RECEIPT]"));
+    assert!(content.contains("tool: exec_shell"));
+    assert!(content.contains("tool_call_id: call-live-big"));
+    assert!(content.contains("detail_handle: sha:"));
+    assert!(content.contains("retrieve: retrieve_tool_result ref=sha:"));
+    assert!(!content.contains(&raw));
+    assert!(
+        content.chars().count()
+            < crate::tool_output_receipts::RAW_TOOL_OUTPUT_RECEIPT_THRESHOLD_CHARS
+    );
+}
+
+#[test]
+fn live_tool_receipt_messages_clones_only_matching_tool_use() {
+    let mut app = App::new(create_test_options(), &Config::default());
+    app.api_messages.push(Message {
+        role: "assistant".to_string(),
+        content: vec![ContentBlock::ToolUse {
+            id: "call-old".to_string(),
+            name: "exec_shell".to_string(),
+            input: serde_json::json!({"command": "old"}),
+            caller: None,
+        }],
+    });
+    app.api_messages.push(Message {
+        role: "user".to_string(),
+        content: vec![ContentBlock::ToolResult {
+            tool_use_id: "call-old".to_string(),
+            content: "OLD_RAW\n".repeat(2_000),
+            is_error: None,
+            content_blocks: None,
+        }],
+    });
+    app.api_messages.push(Message {
+        role: "assistant".to_string(),
+        content: vec![ContentBlock::ToolUse {
+            id: "call-new".to_string(),
+            name: "read_file".to_string(),
+            input: serde_json::json!({"path": "src/main.rs"}),
+            caller: None,
+        }],
+    });
+
+    let messages = live_tool_receipt_messages(&app, "call-new", "NEW_RAW", true);
+
+    assert_eq!(messages.len(), 2);
+    assert!(matches!(
+        &messages[0].content[0],
+        ContentBlock::ToolUse { id, name, .. } if id == "call-new" && name == "read_file"
+    ));
+    assert!(matches!(
+        &messages[1].content[0],
+        ContentBlock::ToolResult { tool_use_id, content, .. }
+            if tool_use_id == "call-new" && content == "NEW_RAW"
+    ));
+}
+
 fn text_message(role: &str, text: &str) -> Message {
     Message {
         role: role.to_string(),
@@ -1286,6 +1475,7 @@ fn saved_session_with_messages(messages: Vec<Message>) -> SavedSession {
             cost: crate::session_manager::SessionCostSnapshot::default(),
             parent_session_id: None,
             forked_from_message_count: None,
+            cumulative_turn_secs: 0,
         },
         messages,
         system_prompt: None,
@@ -1921,17 +2111,43 @@ fn turn_liveness_leaves_active_turn_running() {
     let mut app = create_test_app();
     app.is_loading = true;
     app.runtime_turn_status = Some("in_progress".to_string());
-    app.dispatch_started_at =
-        Some(Instant::now() - DISPATCH_WATCHDOG_TIMEOUT - Duration::from_secs(10));
+    app.turn_started_at = Some(Instant::now() - Duration::from_secs(60));
 
     let recovered = reconcile_turn_liveness(&mut app, Instant::now(), false);
 
     assert!(!recovered);
     assert!(app.is_loading);
-    assert!(app.dispatch_started_at.is_some());
+    assert!(app.turn_started_at.is_some());
     assert!(app.status_toasts.is_empty());
 }
 
+#[test]
+fn turn_liveness_recovers_stalled_in_progress_turn() {
+    let mut app = create_test_app();
+    app.is_loading = true;
+    app.runtime_turn_status = Some("in_progress".to_string());
+    app.runtime_turn_id = Some("stale-turn-id".to_string());
+    app.turn_started_at =
+        Some(Instant::now() - TURN_STALL_WATCHDOG_TIMEOUT - Duration::from_millis(1));
+    app.streaming_message_index = Some(0);
+    app.user_scrolled_during_stream = true;
+
+    let recovered = reconcile_turn_liveness(&mut app, Instant::now(), false);
+
+    assert!(recovered);
+    assert!(!app.is_loading);
+    assert!(app.turn_started_at.is_none());
+    assert!(app.runtime_turn_status.is_none());
+    assert!(app.runtime_turn_id.is_none());
+    assert!(app.dispatch_started_at.is_none());
+    assert!(app.streaming_message_index.is_none());
+    assert!(app.streaming_thinking_active_entry.is_none());
+    assert!(!app.user_scrolled_during_stream);
+    let toast = app.status_toasts.back().expect("stall toast");
+    assert_eq!(toast.level, StatusToastLevel::Error);
+    assert!(toast.text.contains("Turn stalled"));
+}
+
 #[test]
 fn fixed_model_auto_thinking_skips_auto_model_router() {
     let mut app = create_test_app();
@@ -1977,6 +2193,8 @@ fn init_git_repo() -> TempDir {
             "user.name=codewhale Tests",
             "-c",
             "user.email=tests@example.com",
+            "-c",
+            "commit.gpgsign=false",
             "commit",
             "--allow-empty",
             "-m",
@@ -2242,6 +2460,75 @@ fn event_poll_timeout_has_nonzero_floor() {
     );
 }
 
+fn complete_release_json(tag: &str) -> serde_json::Value {
+    let assets = REQUIRED_RELEASE_ASSETS
+        .iter()
+        .map(|name| serde_json::json!({ "name": name, "state": "uploaded" }))
+        .collect::<Vec<_>>();
+    serde_json::json!({
+        "tag_name": tag,
+        "draft": false,
+        "prerelease": false,
+        "assets": assets,
+    })
+}
+
+#[test]
+fn version_hint_requires_complete_release_assets() {
+    let complete = complete_release_json("v0.8.47");
+    let hint = version_hint_from_release_json(&complete, "0.8.46").expect("newer complete release");
+    assert!(hint.contains("v0.8.47 available"));
+
+    let mut missing_manifest = complete_release_json("v0.8.47");
+    missing_manifest["assets"] = serde_json::Value::Array(
+        missing_manifest["assets"]
+            .as_array()
+            .expect("assets")
+            .iter()
+            .filter(|asset| {
+                asset.get("name").and_then(serde_json::Value::as_str)
+                    != Some("codewhale-artifacts-sha256.txt")
+            })
+            .cloned()
+            .collect(),
+    );
+    assert!(
+        version_hint_from_release_json(&missing_manifest, "0.8.46").is_none(),
+        "do not advertise a release before checksums are uploaded"
+    );
+
+    let mut pending_asset = complete_release_json("v0.8.47");
+    pending_asset["assets"].as_array_mut().expect("assets")[0]["state"] = serde_json::json!("open");
+    assert!(
+        version_hint_from_release_json(&pending_asset, "0.8.46").is_none(),
+        "do not advertise a release before every asset is uploaded"
+    );
+
+    let mut missing_state = complete_release_json("v0.8.47");
+    missing_state["assets"].as_array_mut().expect("assets")[0]
+        .as_object_mut()
+        .expect("asset object")
+        .remove("state");
+    assert!(
+        version_hint_from_release_json(&missing_state, "0.8.46").is_none(),
+        "do not accept malformed asset state as uploaded"
+    );
+}
+
+#[test]
+fn version_hint_ignores_draft_prerelease_and_current_versions() {
+    let mut draft = complete_release_json("v0.8.47");
+    draft["draft"] = serde_json::Value::Bool(true);
+    assert!(version_hint_from_release_json(&draft, "0.8.46").is_none());
+
+    let mut prerelease = complete_release_json("v0.8.47");
+    prerelease["prerelease"] = serde_json::Value::Bool(true);
+    assert!(version_hint_from_release_json(&prerelease, "0.8.46").is_none());
+
+    let current = complete_release_json("v0.8.46");
+    assert!(version_hint_from_release_json(&current, "0.8.46").is_none());
+}
+
 #[test]
 #[cfg(any(unix, windows))]
 fn external_url_launcher_does_not_wait_for_browser_process() {
@@ -3139,6 +3426,7 @@ async fn dismissed_plan_prompt_leaves_non_numeric_input_for_normal_send_path() {
 #[tokio::test]
 async fn dispatch_user_message_records_prompt_for_cancel_restore() {
     let mut app = create_test_app();
+    app.show_thinking = false;
     let config = Config::default();
     let mut engine = crate::core::engine::mock_engine_handle();
     let queued = crate::tui::app::QueuedMessage::new("fix this typo\nthen retry".to_string(), None);
@@ -3152,8 +3440,57 @@ async fn dispatch_user_message_records_prompt_for_cancel_restore() {
         Some("fix this typo\nthen retry")
     );
     match engine.rx_op.recv().await.expect("send message op") {
-        crate::core::ops::Op::SendMessage { content, .. } => {
+        crate::core::ops::Op::SendMessage {
+            content,
+            show_thinking,
+            ..
+        } => {
             assert_eq!(content, "fix this typo\nthen retry");
+            assert!(
+                !show_thinking,
+                "dispatch must carry the user's hidden-thinking setting into the engine"
+            );
+        }
+        other => panic!("expected SendMessage, got {other:?}"),
+    }
+}
+
+#[tokio::test]
+async fn startup_prompt_waits_for_onboarding_then_dispatches() {
+    let mut app = create_test_app();
+    app.input = "阅读项目 and wait".to_string();
+    app.cursor_position = app.input.chars().count();
+    app.auto_submit_initial_input = true;
+    app.onboarding = OnboardingState::Welcome;
+    let config = Config::default();
+    let mut engine = crate::core::engine::mock_engine_handle();
+
+    submit_initial_input_if_ready(&mut app, &config, &engine.handle)
+        .await
+        .expect("defer");
+
+    assert!(app.auto_submit_initial_input);
+    assert_eq!(app.input, "阅读项目 and wait");
+    assert_eq!(
+        app.status_message.as_deref(),
+        Some(INITIAL_PROMPT_DEFERRED_STATUS)
+    );
+    assert!(engine.rx_op.try_recv().is_err());
+
+    app.onboarding = OnboardingState::None;
+    submit_initial_input_if_ready(&mut app, &config, &engine.handle)
+        .await
+        .expect("submit");
+
+    assert!(!app.auto_submit_initial_input);
+    assert!(app.input.is_empty());
+    assert_eq!(
+        app.last_submitted_prompt.as_deref(),
+        Some("阅读项目 and wait")
+    );
+    match engine.rx_op.recv().await.expect("send message op") {
+        crate::core::ops::Op::SendMessage { content, .. } => {
+            assert!(content.contains("阅读项目 and wait"));
         }
         other => panic!("expected SendMessage, got {other:?}"),
     }
@@ -3520,6 +3857,8 @@ fn open_tool_details_pager_supports_active_virtual_tool_cell() {
         &[1],
         100,
         app.transcript_render_options(),
+        &app.folded_thinking,
+        None,
     );
     app.viewport.last_transcript_top = 0;
     app.viewport.last_transcript_visible = 4;
@@ -4165,6 +4504,9 @@ fn apply_loaded_session_restores_concrete_model_mode() {
 fn apply_loaded_session_restores_auto_model_mode() {
     let mut app = create_test_app();
     app.set_model_selection("deepseek-v4-pro".to_string());
+    app.reasoning_effort = ReasoningEffort::High;
+    app.last_effective_model = Some("deepseek-v4-flash".to_string());
+    app.last_effective_reasoning_effort = Some(ReasoningEffort::Low);
     let mut session = saved_session_with_messages(vec![
         text_message("user", "hello"),
         text_message("assistant", "hi"),
@@ -4177,6 +4519,10 @@ fn apply_loaded_session_restores_auto_model_mode() {
     assert!(app.auto_model);
     assert_eq!(app.model, "auto");
     assert_eq!(app.model_selection_for_persistence(), "auto");
+    assert_eq!(app.last_effective_model, None);
+    assert_eq!(app.last_effective_reasoning_effort, None);
+    assert_eq!(app.reasoning_effort, ReasoningEffort::Auto);
+    assert_eq!(app.effective_model_for_budget(), DEFAULT_TEXT_MODEL);
 }
 
 #[test]
@@ -4932,6 +5278,10 @@ fn activity_detail_opens_reasoning_timeline_for_selected_thinking() {
         body.contains("Selected chunk: 1 of 2"),
         "chunk position missing: {body}"
     );
+    assert!(
+        body.contains("Next chunk: 2 of 2 - second chunk reasoning"),
+        "neighboring chunk missing: {body}"
+    );
     assert!(body.contains("Thinking chunk 1 of 2 (selected)"), "{body}");
     assert!(body.contains("Thinking chunk 2 of 2"), "{body}");
     assert!(body.contains("first chunk reasoning"), "body: {body}");
@@ -4941,6 +5291,95 @@ fn activity_detail_opens_reasoning_timeline_for_selected_thinking() {
     );
 }
 
+#[test]
+fn activity_detail_includes_tool_handle_and_neighbor_context() {
+    let mut app = create_test_app();
+    app.history = vec![
+        HistoryCell::Thinking {
+            content: "checked approach".to_string(),
+            streaming: false,
+            duration_secs: Some(0.6),
+        },
+        HistoryCell::Tool(ToolCell::Generic(GenericToolCell {
+            name: "read_file".to_string(),
+            status: ToolStatus::Success,
+            input_summary: Some("src/main.rs".to_string()),
+            output: Some("bounded preview".to_string()),
+            prompts: None,
+            spillover_path: None,
+            output_summary: None,
+            is_diff: false,
+        })),
+        HistoryCell::Tool(ToolCell::Generic(GenericToolCell {
+            name: "grep_files".to_string(),
+            status: ToolStatus::Success,
+            input_summary: Some("TODO".to_string()),
+            output: Some("grep summary".to_string()),
+            prompts: None,
+            spillover_path: None,
+            output_summary: None,
+            is_diff: false,
+        })),
+    ];
+    app.tool_details_by_cell.insert(
+        1,
+        ToolDetailRecord {
+            tool_id: "call-read".to_string(),
+            tool_name: "read_file".to_string(),
+            input: serde_json::json!({"path": "src/main.rs"}),
+            output: Some("full output behind raw details".to_string()),
+        },
+    );
+    app.session_artifacts
+        .push(crate::artifacts::ArtifactRecord {
+            id: "art_call-read".to_string(),
+            kind: crate::artifacts::ArtifactKind::ToolOutput,
+            session_id: "session-activity".to_string(),
+            tool_call_id: "call-read".to_string(),
+            tool_name: "read_file".to_string(),
+            created_at: chrono::Utc::now(),
+            byte_size: 42,
+            preview: "bounded preview".to_string(),
+            storage_path: PathBuf::from("artifacts").join("art_call-read.txt"),
+        });
+    app.resync_history_revisions();
+    let revisions = app.history_revisions.clone();
+    app.viewport.transcript_cache.ensure(
+        &app.history,
+        &revisions,
+        100,
+        app.transcript_render_options(),
+    );
+    let line = first_line_for_cell(&app, 1);
+    let point = TranscriptSelectionPoint {
+        line_index: line,
+        column: 0,
+    };
+    app.viewport.transcript_selection.anchor = Some(point);
+    app.viewport.transcript_selection.head = Some(point);
+
+    assert!(open_activity_detail_pager(&mut app));
+    let body = pop_pager_body(&mut app);
+
+    assert!(body.contains("Activity: read_file"), "{body}");
+    assert!(body.contains("Activity chunk: 2 of 3"), "{body}");
+    assert!(
+        body.contains("Previous activity: 1 of 3 - thinking"),
+        "{body}"
+    );
+    assert!(
+        body.contains("Next activity: 3 of 3 - tool grep_files"),
+        "{body}"
+    );
+    assert!(body.contains("Detail handle: art_call-read"), "{body}");
+    assert!(
+        body.contains("retrieve_tool_result ref=art_call-read"),
+        "{body}"
+    );
+    assert!(body.contains("Alt+V"), "{body}");
+    assert!(body.contains("raw details"), "{body}");
+}
+
 #[test]
 fn activity_detail_fallback_prefers_live_activity_context() {
     let mut app = create_test_app();
@@ -4999,6 +5438,11 @@ fn activity_detail_fallback_uses_recent_meaningful_activity_without_full_tool_du
         body.contains("Alt+V for details"),
         "activity detail should stay bounded and point to Alt+V for raw detail: {body}"
     );
+    assert!(body.contains("Detail handle: Alt+V details"), "{body}");
+    assert!(
+        !body.contains("Detail handle: Alt+V raw details"),
+        "fallback tool details should not be labeled raw: {body}"
+    );
     assert!(
         !body.contains("line 10"),
         "middle of large raw output should not be dumped into Activity Detail: {body}"
@@ -5086,6 +5530,49 @@ fn message_complete_drain_preserves_thinking_when_thinking_complete_lost() {
     );
 }
 
+#[test]
+fn approval_prompt_uses_event_input_after_message_complete_drain() {
+    let mut app = create_test_app();
+    app.pending_tool_uses.push((
+        "tool-1".to_string(),
+        "exec_shell".to_string(),
+        serde_json::json!({"command": "stale value from drained list"}),
+    ));
+
+    // Mirror the old race: MessageComplete drains pending tool uses before
+    // ApprovalRequired is handled. The approval modal must still show the
+    // non-empty input carried directly on the ApprovalRequired event.
+    app.pending_tool_uses.clear();
+
+    let event_input = serde_json::json!({
+        "command": "cargo test -p codewhale-tui approval",
+        "workdir": "/repo",
+    });
+    push_approval_request_view(
+        &mut app,
+        "tool-1",
+        "exec_shell",
+        "Run cargo tests",
+        &event_input,
+        "approval-key",
+    );
+
+    let mut view = app.view_stack.pop().expect("approval view");
+    let approval = view
+        .as_any_mut()
+        .downcast_mut::<ApprovalView>()
+        .expect("approval view");
+    let action = approval.handle_key(KeyEvent::new(KeyCode::Char('v'), KeyModifiers::NONE));
+    let ViewAction::Emit(ViewEvent::OpenTextPager { content, .. }) = action else {
+        panic!("expected approval params pager");
+    };
+
+    assert!(content.contains("cargo test -p codewhale-tui approval"));
+    assert!(content.contains("/repo"));
+    assert!(!content.contains("stale value from drained list"));
+    assert_ne!(content.trim(), "{}");
+}
+
 #[test]
 fn second_thinking_block_appends_new_entry_in_same_active_cell() {
     // Real V4 turns can emit Thinking → Tool → Thinking → Tool before any
@@ -5578,6 +6065,10 @@ fn default_footer_keeps_prefix_stability_opt_in() {
         items.contains(&crate::config::StatusItem::Cache),
         "default footer should still include provider-reported cache hit rate"
     );
+    assert!(
+        items.contains(&crate::config::StatusItem::GitBranch),
+        "default footer should surface the current workspace branch"
+    );
 }
 
 #[test]
@@ -5661,11 +6152,37 @@ fn render_footer_from_git_branch_item_renders_workspace_branch() {
 
     let mut app = create_test_app();
     app.workspace = repo.path().to_path_buf();
+    crate::tui::workspace_context::refresh_if_needed(&mut app, Instant::now(), true);
 
     let props = render_footer_from(&app, &[crate::config::StatusItem::GitBranch], None);
     assert_eq!(spans_text(&props.cache), "feature/statusline");
 }
 
+#[test]
+fn default_footer_renders_workspace_branch_when_available() {
+    let repo = init_git_repo();
+    let checkout = Command::new("git")
+        .args(["checkout", "-b", "feature/default-branch-chip"])
+        .current_dir(repo.path())
+        .output()
+        .expect("git checkout should run");
+    assert!(
+        checkout.status.success(),
+        "git checkout failed: {}",
+        String::from_utf8_lossy(&checkout.stderr)
+    );
+
+    let mut app = create_test_app();
+    app.workspace = repo.path().to_path_buf();
+    crate::tui::workspace_context::refresh_if_needed(&mut app, Instant::now(), true);
+
+    let props = render_footer_from(&app, &crate::config::StatusItem::default_footer(), None);
+    assert!(
+        spans_text(&props.cache).contains("feature/default-branch-chip"),
+        "default footer should include the current git branch"
+    );
+}
+
 /// Regression for issue #244: visible session spend must not decrease.
 /// Sub-agent token usage events arrive out of order and may be reconciled
 /// later (cache adjustments, provisional → final swap). The displayed total
@@ -5971,16 +6488,15 @@ fn composer_arrows_scroll_defaults_true_without_mouse_capture() {
 }
 
 #[test]
-fn composer_arrows_scroll_defaults_follow_platform_with_mouse_capture() {
+fn composer_arrows_scroll_defaults_false_with_mouse_capture() {
     let options = TuiOptions {
         use_mouse_capture: true,
         ..create_test_options()
     };
     let app = App::new(options, &Config::default());
-    assert_eq!(
-        app.composer_arrows_scroll,
-        cfg!(windows),
-        "arrows-scroll should default to true on Windows and false on other platforms when mouse capture is on"
+    assert!(
+        !app.composer_arrows_scroll,
+        "arrows-scroll must default to false when mouse capture is on"
     );
 }
 
@@ -6089,6 +6605,7 @@ fn notification_settings_tui_always_keeps_configured_method_no_threshold() {
         notifications: Some(crate::config::NotificationsConfig {
             method: crate::config::NotificationMethod::Bel,
             threshold_secs: 120,
+            completion_sound: crate::config::CompletionSound::Beep,
             include_summary: true,
         }),
         ..Config::default()
@@ -6120,6 +6637,7 @@ fn notification_settings_no_tui_override_uses_notifications_block() {
         notifications: Some(crate::config::NotificationsConfig {
             method: crate::config::NotificationMethod::Osc9,
             threshold_secs: 45,
+            completion_sound: crate::config::CompletionSound::Beep,
             include_summary: false,
         }),
         ..Config::default()
diff --git a/crates/tui/src/tui/ui_text.rs b/crates/tui/src/tui/ui_text.rs
index daafddb5..6c01743d 100644
--- a/crates/tui/src/tui/ui_text.rs
+++ b/crates/tui/src/tui/ui_text.rs
@@ -6,6 +6,24 @@ use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};
 use crate::tui::history::HistoryCell;
 use crate::tui::osc8;
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum CopyLineSeparator {
+    None,
+    Space,
+    Newline,
+}
+
+impl CopyLineSeparator {
+    #[must_use]
+    pub(crate) const fn as_str(self) -> &'static str {
+        match self {
+            Self::None => "",
+            Self::Space => " ",
+            Self::Newline => "\n",
+        }
+    }
+}
+
 pub(crate) fn truncate_line_to_width(text: &str, max_width: usize) -> String {
     if max_width == 0 {
         return String::new();
diff --git a/crates/tui/src/tui/views/mod.rs b/crates/tui/src/tui/views/mod.rs
index c50c83c0..27b24192 100644
--- a/crates/tui/src/tui/views/mod.rs
+++ b/crates/tui/src/tui/views/mod.rs
@@ -3,6 +3,7 @@ use ratatui::{buffer::Buffer, layout::Rect};
 use std::cell::{Cell, RefCell};
 use std::fmt;
 
+use crate::config::Config;
 use crate::localization::{Locale, MessageId, tr};
 use crate::palette;
 use crate::settings::Settings;
@@ -45,7 +46,6 @@ pub enum CommandPaletteAction {
     ExecuteCommand { command: String },
     InsertText { text: String },
     OpenTextPager { title: String, content: String },
-    VoiceInput,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -157,6 +157,11 @@ pub enum ViewEvent {
         provider: crate::config::ApiProvider,
         api_key: String,
     },
+    /// Emitted by the `/provider` picker when Kimi CLI OAuth credentials can
+    /// be reused for Moonshot/Kimi dispatch.
+    ProviderPickerKimiOAuthEnabled {
+        provider: crate::config::ApiProvider,
+    },
     /// Emitted by the `/mode` picker when the user chooses a mode.
     ModeSelected {
         mode: crate::tui::app::AppMode,
@@ -570,6 +575,7 @@ pub struct ConfigView {
     filter: String,
     status: Option<String>,
     locale: Locale,
+    effective_cost_currency: String,
     last_visible_rows: Cell<usize>,
     last_row_hitboxes: RefCell<Vec<(u16, usize)>>,
 }
@@ -610,6 +616,15 @@ impl ConfigView {
                 editable: true,
                 scope: ConfigScope::Saved,
             },
+            ConfigRow {
+                section: ConfigSection::Model,
+                key: "base_url".to_string(),
+                value: Config::load(app.config_path.clone(), app.config_profile.as_deref())
+                    .map(|config| config.deepseek_base_url())
+                    .unwrap_or_else(|_| "(unavailable)".to_string()),
+                editable: true,
+                scope: ConfigScope::Saved,
+            },
             ConfigRow {
                 section: ConfigSection::Permissions,
                 key: "approval_mode".to_string(),
@@ -746,23 +761,6 @@ impl ConfigView {
                 editable: true,
                 scope: ConfigScope::Saved,
             },
-            ConfigRow {
-                section: ConfigSection::Composer,
-                key: "voice_input_command".to_string(),
-                value: settings
-                    .voice_input_command
-                    .clone()
-                    .unwrap_or_else(|| "(not configured)".to_string()),
-                editable: true,
-                scope: ConfigScope::Saved,
-            },
-            ConfigRow {
-                section: ConfigSection::Composer,
-                key: "voice_input_timeout_secs".to_string(),
-                value: settings.voice_input_timeout_secs.to_string(),
-                editable: true,
-                scope: ConfigScope::Saved,
-            },
             ConfigRow {
                 section: ConfigSection::Sidebar,
                 key: "sidebar_width".to_string(),
@@ -822,6 +820,7 @@ impl ConfigView {
             filter: String::new(),
             status: None,
             locale: app.ui_locale,
+            effective_cost_currency: cost_currency_config_value(app),
             last_visible_rows: Cell::new(0),
             last_row_hitboxes: RefCell::new(Vec::new()),
         }
@@ -844,7 +843,7 @@ impl ConfigView {
 
         let section = row.section.label().to_lowercase();
         let key = row.key.to_lowercase();
-        let value = row.value.to_lowercase();
+        let value = self.row_display_value(row).to_lowercase();
         let scope = row.scope.label().to_lowercase();
 
         filter.split_whitespace().all(|term| {
@@ -1123,6 +1122,27 @@ impl ConfigView {
 
         self.update_filter(|filter| filter.clear());
     }
+
+    fn row_display_value(&self, row: &ConfigRow) -> String {
+        if row.key == "cost_currency" && row.scope == ConfigScope::Saved {
+            let saved_cost_currency = crate::pricing::CostCurrency::from_setting(&row.value);
+            let effective_cost_currency =
+                crate::pricing::CostCurrency::from_setting(&self.effective_cost_currency);
+            if saved_cost_currency != effective_cost_currency {
+                return format!("{} (effective {})", row.value, self.effective_cost_currency);
+            }
+        }
+
+        row.value.clone()
+    }
+}
+
+fn cost_currency_config_value(app: &App) -> String {
+    match app.cost_currency {
+        crate::pricing::CostCurrency::Usd => "usd",
+        crate::pricing::CostCurrency::Cny => "cny",
+    }
+    .to_string()
 }
 
 fn config_hint_for_key(key: &str) -> &'static str {
@@ -1140,14 +1160,14 @@ fn config_hint_for_key(key: &str) -> &'static str {
         "theme" => "system | dark | light | grayscale",
         "locale" => "auto | en | ja | zh-Hans | pt-BR",
         "background_color" => "#RRGGBB | default",
+        "base_url" => "save user config; e.g. https://api.deepseek.com/beta or https://gateway/v1",
+        "cost_currency" => "usd | cny",
         "default_mode" => "agent | plan | yolo",
         "sidebar_width" => "10..=50",
         "sidebar_focus" => "auto | work | tasks | agents | context | hidden",
         "max_history" => "integer (0 allowed)",
         "default_model" => "deepseek-v4-pro | deepseek-v4-flash | deepseek-* | none/default",
         "reasoning_effort" => "auto | off | low | medium | high | max | default",
-        "voice_input_command" => "command string | none/default",
-        "voice_input_timeout_secs" => "1..=600",
         "mcp_config_path" => "path to mcp.json",
         _ => "",
     }
@@ -1449,7 +1469,10 @@ impl ModalView for ConfigView {
                         } else {
                             Style::default().fg(palette::TEXT_PRIMARY)
                         };
-                        let value = truncate_view_text(&row.value, CONFIG_VALUE_COLUMN_WIDTH);
+                        let value = truncate_view_text(
+                            &self.row_display_value(row),
+                            CONFIG_VALUE_COLUMN_WIDTH,
+                        );
                         let mut line = Line::from(format!(
                             "  {:<key_width$} {:<value_width$} {}",
                             row.key,
@@ -2028,7 +2051,52 @@ mod tests {
         KeyCode, KeyEvent, KeyModifiers, MouseButton, MouseEvent, MouseEventKind,
     };
     use ratatui::{buffer::Buffer, layout::Rect};
+    use std::ffi::OsString;
+    use std::fs;
     use std::path::PathBuf;
+    use std::sync::MutexGuard;
+    use tempfile::TempDir;
+
+    struct ConfigSettingsEnvGuard {
+        _tmp: TempDir,
+        previous_config_path: Option<OsString>,
+        _lock: MutexGuard<'static, ()>,
+    }
+
+    impl ConfigSettingsEnvGuard {
+        fn new(settings_toml: &str) -> Self {
+            let lock = crate::test_support::lock_test_env();
+            let tmp = TempDir::new().expect("settings tempdir");
+            let config_path = tmp.path().join(".deepseek").join("config.toml");
+            let settings_path = config_path
+                .parent()
+                .expect("settings parent")
+                .join("settings.toml");
+            std::fs::create_dir_all(config_path.parent().expect("config parent"))
+                .expect("config dir");
+            std::fs::write(&settings_path, settings_toml).expect("settings file");
+            let previous_config_path = std::env::var_os("DEEPSEEK_CONFIG_PATH");
+            unsafe {
+                std::env::set_var("DEEPSEEK_CONFIG_PATH", &config_path);
+            }
+            Self {
+                _tmp: tmp,
+                previous_config_path,
+                _lock: lock,
+            }
+        }
+    }
+
+    impl Drop for ConfigSettingsEnvGuard {
+        fn drop(&mut self) {
+            unsafe {
+                match self.previous_config_path.take() {
+                    Some(previous) => std::env::set_var("DEEPSEEK_CONFIG_PATH", previous),
+                    None => std::env::remove_var("DEEPSEEK_CONFIG_PATH"),
+                }
+            }
+        }
+    }
 
     fn create_test_app() -> App {
         let options = TuiOptions {
@@ -2055,6 +2123,26 @@ mod tests {
         App::new(options, &Config::default())
     }
 
+    fn cost_currency_row_for_settings(
+        settings_toml: &str,
+    ) -> (String, String, crate::pricing::CostCurrency, Locale) {
+        let _guard = ConfigSettingsEnvGuard::new(settings_toml);
+        let app = create_test_app();
+        let view = ConfigView::new_for_app(&app);
+        let row = view
+            .rows
+            .iter()
+            .find(|row| row.key == "cost_currency")
+            .expect("cost_currency row");
+
+        (
+            row.value.clone(),
+            view.row_display_value(row),
+            app.cost_currency,
+            app.ui_locale,
+        )
+    }
+
     fn type_filter(view: &mut ConfigView, text: &str) {
         for ch in text.chars() {
             let action = view.handle_key(KeyEvent::new(KeyCode::Char(ch), KeyModifiers::NONE));
@@ -2190,6 +2278,7 @@ mod tests {
             .collect::<Vec<_>>();
         assert!(keys.contains(&"model"));
         assert!(keys.contains(&"reasoning_effort"));
+        assert!(keys.contains(&"base_url"));
         assert!(keys.contains(&"approval_mode"));
         assert!(keys.contains(&"theme"));
         assert!(keys.contains(&"locale"));
@@ -2201,8 +2290,6 @@ mod tests {
         assert!(keys.contains(&"composer_border"));
         assert!(keys.contains(&"composer_vim_mode"));
         assert!(keys.contains(&"bracketed_paste"));
-        assert!(keys.contains(&"voice_input_command"));
-        assert!(keys.contains(&"voice_input_timeout_secs"));
         assert!(keys.contains(&"context_panel"));
         assert!(keys.contains(&"cost_currency"));
         assert!(keys.contains(&"prefer_external_pdftotext"));
@@ -2210,6 +2297,88 @@ mod tests {
         assert!(view.rows.iter().all(|row| row.editable));
     }
 
+    #[test]
+    fn config_view_base_url_reflects_app_config_path() {
+        let temp_root = std::env::temp_dir().join(format!(
+            "deepseek-tui-base-url-view-test-{}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&temp_root).unwrap();
+        let config_path = temp_root.join("config.toml");
+        fs::write(
+            &config_path,
+            "base_url = \"https://ui-config-view.local/v1\"\n",
+        )
+        .unwrap();
+
+        let mut app = create_test_app();
+        app.config_path = Some(config_path.clone());
+        let view = ConfigView::new_for_app(&app);
+
+        let row = view
+            .rows
+            .iter()
+            .find(|row| row.key == "base_url")
+            .expect("base_url row missing");
+        assert_eq!(row.value, "https://ui-config-view.local/v1");
+    }
+
+    #[test]
+    fn config_view_cost_currency_shows_saved_and_effective_runtime_currency() {
+        let _guard = ConfigSettingsEnvGuard::new("locale = \"zh-Hans\"\ncost_currency = \"usd\"\n");
+        let app = create_test_app();
+        assert_eq!(app.ui_locale, Locale::ZhHans);
+        assert_eq!(app.cost_currency, crate::pricing::CostCurrency::Cny);
+
+        let view = ConfigView::new_for_app(&app);
+        let row = view
+            .rows
+            .iter()
+            .find(|row| row.key == "cost_currency")
+            .expect("cost_currency row");
+
+        assert_eq!(row.value, "usd");
+        assert_eq!(view.row_display_value(row), "usd (effective cny)");
+        assert_eq!(Settings::load().expect("settings").cost_currency, "usd");
+    }
+
+    #[test]
+    fn config_view_cost_currency_aliases_matching_effective_currency_are_silent() {
+        for alias in ["rmb", "yuan", "¥"] {
+            let (saved_value, display_value, effective_currency, locale) =
+                cost_currency_row_for_settings(&format!(
+                    "locale = \"zh-Hans\"\ncost_currency = \"{alias}\"\n"
+                ));
+
+            assert_eq!(locale, Locale::ZhHans);
+            assert_eq!(effective_currency, crate::pricing::CostCurrency::Cny);
+            assert_eq!(saved_value, alias);
+            assert_eq!(display_value, alias);
+        }
+    }
+
+    #[test]
+    fn config_view_cost_currency_matching_cny_setting_is_silent() {
+        let (saved_value, display_value, effective_currency, locale) =
+            cost_currency_row_for_settings("locale = \"zh-Hans\"\ncost_currency = \"cny\"\n");
+
+        assert_eq!(locale, Locale::ZhHans);
+        assert_eq!(effective_currency, crate::pricing::CostCurrency::Cny);
+        assert_eq!(saved_value, "cny");
+        assert_eq!(display_value, "cny");
+    }
+
+    #[test]
+    fn config_view_cost_currency_non_zh_hans_locale_uses_saved_currency() {
+        let (saved_value, display_value, effective_currency, locale) =
+            cost_currency_row_for_settings("locale = \"en\"\ncost_currency = \"cny\"\n");
+
+        assert_eq!(locale, Locale::En);
+        assert_eq!(effective_currency, crate::pricing::CostCurrency::Cny);
+        assert_eq!(saved_value, "cny");
+        assert_eq!(display_value, "cny");
+    }
+
     #[test]
     fn config_view_exposes_all_available_saved_settings() {
         let app = create_test_app();
diff --git a/crates/tui/src/tui/views/status_picker.rs b/crates/tui/src/tui/views/status_picker.rs
index 2cbf576e..2d1a4362 100644
--- a/crates/tui/src/tui/views/status_picker.rs
+++ b/crates/tui/src/tui/views/status_picker.rs
@@ -19,8 +19,12 @@ use ratatui::{
 };
 
 use crate::config::StatusItem;
+use crate::localization::truncate_to_width;
 use crate::palette;
 use crate::tui::views::{ModalKind, ModalView, ViewAction, ViewEvent};
+use unicode_width::UnicodeWidthStr;
+
+const STATUS_PICKER_SELECTION_BG: ratatui::style::Color = ratatui::style::Color::Rgb(54, 72, 104);
 
 /// Picker state. We hold both the user's working selection AND the original
 /// snapshot so Esc can perfectly revert the live preview.
@@ -62,16 +66,21 @@ impl StatusPickerView {
     }
 
     fn move_up(&mut self) {
-        if self.cursor > 0 {
+        if self.rows.is_empty() {
+            return;
+        }
+        if self.cursor == 0 {
+            self.cursor = self.rows.len() - 1;
+        } else {
             self.cursor -= 1;
         }
     }
 
     fn move_down(&mut self) {
-        let max = self.rows.len().saturating_sub(1);
-        if self.cursor < max {
-            self.cursor += 1;
+        if self.rows.is_empty() {
+            return;
         }
+        self.cursor = (self.cursor + 1) % self.rows.len();
     }
 
     fn toggle_current(&mut self) {
@@ -201,10 +210,19 @@ impl ModalView for StatusPickerView {
         )));
         lines.push(Line::from(""));
 
-        for (idx, item) in self.rows.iter().enumerate() {
+        let visible_rows = inner.height.saturating_sub(2) as usize;
+        let row_start = visible_row_start(self.rows.len(), self.cursor, visible_rows);
+
+        for (idx, item) in self
+            .rows
+            .iter()
+            .enumerate()
+            .skip(row_start)
+            .take(visible_rows)
+        {
             let checked = *self.selected.get(idx).unwrap_or(&false);
             let is_cursor = idx == self.cursor;
-            let mark = if checked { "[x]" } else { "[ ]" };
+            let mark = if checked { "[✓]" } else { "[ ]" };
 
             let row_style = if is_cursor {
                 Style::default()
@@ -225,20 +243,50 @@ impl ModalView for StatusPickerView {
             };
             let pointer = if is_cursor { "▸" } else { " " };
 
-            lines.push(Line::from(vec![
-                Span::styled(format!(" {pointer} "), row_style),
-                Span::styled(mark.to_string(), row_style),
-                Span::raw(" "),
-                Span::styled(item.label().to_string(), row_style),
-                Span::raw("  "),
-                Span::styled(format!("({})", item.hint()), hint_style),
-            ]));
+            if is_cursor {
+                let selected_style = Style::default()
+                    .fg(palette::SELECTION_TEXT)
+                    .bg(STATUS_PICKER_SELECTION_BG)
+                    .add_modifier(Modifier::BOLD);
+                let line = status_row_text(pointer, mark, item, inner.width as usize);
+                lines.push(Line::from(Span::styled(line, selected_style)));
+            } else {
+                lines.push(Line::from(vec![
+                    Span::styled(format!(" {pointer} "), row_style),
+                    Span::styled(mark.to_string(), row_style),
+                    Span::styled(" ", row_style),
+                    Span::styled(item.label().to_string(), row_style),
+                    Span::styled("  ", row_style),
+                    Span::styled(format!("({})", item.hint()), hint_style),
+                ]));
+            }
         }
 
         Paragraph::new(lines).render(inner, buf);
     }
 }
 
+fn visible_row_start(total_rows: usize, cursor: usize, visible_rows: usize) -> usize {
+    if total_rows == 0 || visible_rows == 0 || total_rows <= visible_rows {
+        return 0;
+    }
+    let max_start = total_rows - visible_rows;
+    cursor
+        .saturating_add(1)
+        .saturating_sub(visible_rows)
+        .min(max_start)
+}
+
+fn status_row_text(pointer: &str, mark: &str, item: &StatusItem, width: usize) -> String {
+    let text = format!(" {pointer} {mark} {}  ({})", item.label(), item.hint());
+    let mut text = truncate_to_width(&text, width);
+    let current_width = text.width();
+    if current_width < width {
+        text.push_str(&" ".repeat(width - current_width));
+    }
+    text
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -317,18 +365,32 @@ mod tests {
     }
 
     #[test]
-    fn arrow_keys_move_cursor_within_bounds() {
+    fn arrow_keys_wrap_cursor_at_edges() {
         let active = StatusItem::default_footer();
         let mut view = StatusPickerView::new(&active);
         assert_eq!(view.cursor, 0);
+        view.handle_key(KeyEvent::new(KeyCode::Up, KeyModifiers::NONE));
+        assert_eq!(view.cursor, StatusItem::all().len() - 1);
+        view.handle_key(KeyEvent::new(KeyCode::Down, KeyModifiers::NONE));
+        assert_eq!(view.cursor, 0);
         view.handle_key(KeyEvent::new(KeyCode::Down, KeyModifiers::NONE));
         assert_eq!(view.cursor, 1);
         view.handle_key(KeyEvent::new(KeyCode::Up, KeyModifiers::NONE));
         assert_eq!(view.cursor, 0);
-        // Move past the bottom shouldn't wrap.
-        for _ in 0..StatusItem::all().len() + 5 {
-            view.handle_key(KeyEvent::new(KeyCode::Down, KeyModifiers::NONE));
-        }
-        assert_eq!(view.cursor, StatusItem::all().len() - 1);
+    }
+
+    #[test]
+    fn visible_row_start_keeps_cursor_in_view() {
+        assert_eq!(visible_row_start(14, 0, 8), 0);
+        assert_eq!(visible_row_start(14, 7, 8), 0);
+        assert_eq!(visible_row_start(14, 8, 8), 1);
+        assert_eq!(visible_row_start(14, 13, 8), 6);
+    }
+
+    #[test]
+    fn selected_row_text_fills_available_width() {
+        let text = status_row_text("▸", "[ ]", &StatusItem::LastToolElapsed, 40);
+        assert_eq!(text.width(), 40);
+        assert!(text.starts_with(" ▸ [ ] Last tool elapsed"));
     }
 }
diff --git a/crates/tui/src/tui/voice_input.rs b/crates/tui/src/tui/voice_input.rs
deleted file mode 100644
index 04f57e8a..00000000
--- a/crates/tui/src/tui/voice_input.rs
+++ /dev/null
@@ -1,127 +0,0 @@
-//! Voice-input command bridge for the composer.
-//!
-//! CodeWhale stays out of platform microphone APIs here. A configured command
-//! owns recording and speech-to-text, writes the final transcript to stdout,
-//! and the TUI inserts that transcript into the composer.
-
-use std::path::Path;
-use std::process::Stdio;
-use std::time::Duration;
-
-use anyhow::{Context, Result, anyhow};
-use tokio::process::Command as TokioCommand;
-
-const DEFAULT_TIMEOUT_SECS: u64 = 60;
-const MAX_TIMEOUT_SECS: u64 = 600;
-
-pub(crate) fn clamp_timeout_secs(secs: u64) -> u64 {
-    secs.clamp(1, MAX_TIMEOUT_SECS)
-}
-
-pub(crate) fn default_timeout_secs() -> u64 {
-    DEFAULT_TIMEOUT_SECS
-}
-
-fn parse_voice_command(command_line: &str) -> Result<(String, Vec<String>)> {
-    let trimmed = command_line.trim();
-    if trimmed.is_empty() {
-        return Err(anyhow!("voice_input_command is empty"));
-    }
-
-    let parts = shlex::split(trimmed).ok_or_else(|| {
-        anyhow!("voice_input_command has invalid quoting; check spaces and quote pairs")
-    })?;
-    let Some((program, args)) = parts.split_first() else {
-        return Err(anyhow!("voice_input_command is empty"));
-    };
-    Ok((program.clone(), args.to_vec()))
-}
-
-fn stdout_to_transcript(stdout: &[u8]) -> Option<String> {
-    let text = String::from_utf8_lossy(stdout);
-    let transcript = text.trim();
-    (!transcript.is_empty()).then(|| transcript.to_string())
-}
-
-fn stderr_summary(stderr: &[u8]) -> String {
-    let text = String::from_utf8_lossy(stderr);
-    let trimmed = text.trim();
-    if trimmed.is_empty() {
-        return String::new();
-    }
-    let mut summary: String = trimmed.chars().take(300).collect();
-    if trimmed.chars().count() > 300 {
-        summary.push_str("...");
-    }
-    format!(": {summary}")
-}
-
-pub(crate) async fn run_configured_voice_command(
-    command_line: &str,
-    timeout_secs: u64,
-    cwd: &Path,
-) -> Result<String> {
-    let timeout_secs = clamp_timeout_secs(timeout_secs);
-    let (program, args) = parse_voice_command(command_line)?;
-
-    let mut command = TokioCommand::new(&program);
-    command
-        .args(args)
-        .current_dir(cwd)
-        .stdin(Stdio::null())
-        .stdout(Stdio::piped())
-        .stderr(Stdio::piped())
-        .kill_on_drop(true);
-
-    let output = tokio::time::timeout(Duration::from_secs(timeout_secs), command.output())
-        .await
-        .map_err(|_| anyhow!("voice input command timed out after {timeout_secs}s"))?
-        .with_context(|| format!("failed to run voice input command `{program}`"))?;
-
-    if !output.status.success() {
-        return Err(anyhow!(
-            "voice input command exited with {}{}",
-            output.status,
-            stderr_summary(&output.stderr)
-        ));
-    }
-
-    stdout_to_transcript(&output.stdout)
-        .ok_or_else(|| anyhow!("voice input command produced no transcript on stdout"))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn parses_quoted_voice_command() {
-        let (program, args) =
-            parse_voice_command(r#"python3 "/tmp/codewhale voice.py" --lang en-US"#)
-                .expect("parse command");
-        assert_eq!(program, "python3");
-        assert_eq!(args, vec!["/tmp/codewhale voice.py", "--lang", "en-US"]);
-    }
-
-    #[test]
-    fn rejects_invalid_voice_command_quoting() {
-        let err = parse_voice_command(r#"python3 "unterminated"#).expect_err("bad quotes");
-        assert!(err.to_string().contains("invalid quoting"));
-    }
-
-    #[test]
-    fn trims_stdout_to_transcript() {
-        assert_eq!(
-            stdout_to_transcript(b"\n  ship the voice input feature\r\n").as_deref(),
-            Some("ship the voice input feature")
-        );
-        assert!(stdout_to_transcript(b"\n\t ").is_none());
-    }
-
-    #[test]
-    fn timeout_clamps_to_supported_range() {
-        assert_eq!(clamp_timeout_secs(0), 1);
-        assert_eq!(clamp_timeout_secs(30), 30);
-        assert_eq!(clamp_timeout_secs(999), MAX_TIMEOUT_SECS);
-    }
-}
diff --git a/crates/tui/src/tui/whale_routes.rs b/crates/tui/src/tui/whale_routes.rs
new file mode 100644
index 00000000..d4ef086f
--- /dev/null
+++ b/crates/tui/src/tui/whale_routes.rs
@@ -0,0 +1,187 @@
+//! Whale-size route taxonomy for model + thinking-effort combinations (#2026).
+//!
+//! Maps each `(model, reasoning_effort)` pair to a friendly whale-species label,
+//! sorted from largest/deepest to smallest/fastest. The labels share the same
+//! species pool as sub-agent nicknames (#2016) but serve a different purpose:
+//! route/tier names help users understand depth/cost/speed at a glance.
+//!
+//! ## Route ordering (size → speed)
+//!
+//! 1. Blue Whale   — Pro + max thinking (largest, deepest)
+//! 2. Fin Whale    — Pro + high thinking
+//! 3. Sperm Whale  — Pro + no thinking
+//! 4. Humpback     — Flash + max thinking
+//! 5. Minke Whale  — Flash + high thinking
+//! 6. Beluga       — Flash + no thinking (smallest, fastest)
+//!
+//! Unknown or non-DeepSeek models fall back to the raw model id without
+//! fake whale labeling.
+
+use crate::tui::app::ReasoningEffort;
+
+/// One whale-sized route: a model + thinking-effort combination with
+/// a friendly label, sort order, and descriptive hint.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WhaleRoute {
+    /// Whale-species label, e.g. "Blue Whale".
+    pub label: &'static str,
+    /// Model id, e.g. "deepseek-v4-pro".
+    pub model: &'static str,
+    /// Reasoning effort tier.
+    pub effort: ReasoningEffort,
+    /// Sort index (0 = largest / deepest).
+    pub sort_order: usize,
+    /// Short inline hint, e.g. "Pro + max thinking".
+    pub hint: &'static str,
+    /// Longer description for tooltips / route receipts.
+    pub description: &'static str,
+}
+
+/// Six canonical routes, sorted largest → smallest.
+pub const WHALE_ROUTES: &[WhaleRoute] = &[
+    WhaleRoute {
+        label: "Blue Whale",
+        model: "deepseek-v4-pro",
+        effort: ReasoningEffort::Max,
+        sort_order: 0,
+        hint: "Pro + max thinking",
+        description: "Flagship reasoning at maximum depth — architecture, debugging, security reviews",
+    },
+    WhaleRoute {
+        label: "Fin Whale",
+        model: "deepseek-v4-pro",
+        effort: ReasoningEffort::High,
+        sort_order: 1,
+        hint: "Pro + high thinking",
+        description: "Deep reasoning for complex tasks — multi-file refactors, careful planning",
+    },
+    WhaleRoute {
+        label: "Sperm Whale",
+        model: "deepseek-v4-pro",
+        effort: ReasoningEffort::Off,
+        sort_order: 2,
+        hint: "Pro + no thinking",
+        description: "Full model power without reasoning overhead — straightforward code generation",
+    },
+    WhaleRoute {
+        label: "Humpback",
+        model: "deepseek-v4-flash",
+        effort: ReasoningEffort::Max,
+        sort_order: 3,
+        hint: "Flash + max thinking",
+        description: "Fast model with reasoning depth — lightweight analysis, first-pass reviews",
+    },
+    WhaleRoute {
+        label: "Minke Whale",
+        model: "deepseek-v4-flash",
+        effort: ReasoningEffort::High,
+        sort_order: 4,
+        hint: "Flash + high thinking",
+        description: "Fast model, moderate reasoning — tool execution, read-only scouting",
+    },
+    WhaleRoute {
+        label: "Beluga",
+        model: "deepseek-v4-flash",
+        effort: ReasoningEffort::Off,
+        sort_order: 5,
+        hint: "Flash + no thinking",
+        description: "Fastest and cheapest — lookups, searches, simple edits",
+    },
+];
+
+impl WhaleRoute {
+    /// Look up the whale route for a given model id and reasoning effort.
+    /// Returns `None` for non-DeepSeek models or unrecognized combinations.
+    #[must_use]
+    #[allow(dead_code)]
+    pub fn for_model_effort(model: &str, effort: ReasoningEffort) -> Option<&'static WhaleRoute> {
+        WHALE_ROUTES
+            .iter()
+            .find(|r| r.model.eq_ignore_ascii_case(model) && r.effort == effort)
+    }
+
+    /// Look up a whale route by its sort-order index.
+    #[must_use]
+    #[allow(dead_code)]
+    pub fn by_sort_order(index: usize) -> Option<&'static WhaleRoute> {
+        WHALE_ROUTES.iter().find(|r| r.sort_order == index)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn routes_are_sorted_by_size() {
+        for window in WHALE_ROUTES.windows(2) {
+            assert!(
+                window[0].sort_order < window[1].sort_order,
+                "{} should sort before {}",
+                window[0].label,
+                window[1].label
+            );
+        }
+    }
+
+    #[test]
+    fn lookup_blue_whale_for_pro_max() {
+        let route = WhaleRoute::for_model_effort("deepseek-v4-pro", ReasoningEffort::Max)
+            .expect("blue whale route exists");
+        assert_eq!(route.label, "Blue Whale");
+        assert_eq!(route.model, "deepseek-v4-pro");
+        assert_eq!(route.effort, ReasoningEffort::Max);
+        assert_eq!(route.sort_order, 0);
+    }
+
+    #[test]
+    fn lookup_beluga_for_flash_off() {
+        let route = WhaleRoute::for_model_effort("deepseek-v4-flash", ReasoningEffort::Off)
+            .expect("beluga route exists");
+        assert_eq!(route.label, "Beluga");
+        assert_eq!(route.sort_order, 5);
+    }
+
+    #[test]
+    fn lookup_case_insensitive_model() {
+        let route = WhaleRoute::for_model_effort("DeepSeek-V4-Pro", ReasoningEffort::High)
+            .expect("case-insensitive match");
+        assert_eq!(route.label, "Fin Whale");
+    }
+
+    #[test]
+    fn unknown_model_returns_none() {
+        assert!(WhaleRoute::for_model_effort("gpt-4o", ReasoningEffort::High).is_none());
+    }
+
+    #[test]
+    fn unknown_effort_with_valid_model_returns_none() {
+        // ReasoningEffort::Auto is not in any whale route
+        assert!(WhaleRoute::for_model_effort("deepseek-v4-pro", ReasoningEffort::Auto).is_none());
+    }
+
+    #[test]
+    fn by_sort_order_finds_correct_routes() {
+        assert_eq!(WhaleRoute::by_sort_order(0).unwrap().label, "Blue Whale");
+        assert_eq!(WhaleRoute::by_sort_order(5).unwrap().label, "Beluga");
+        assert!(WhaleRoute::by_sort_order(99).is_none());
+    }
+
+    #[test]
+    fn every_route_has_unique_sort_order() {
+        let orders: Vec<usize> = WHALE_ROUTES.iter().map(|r| r.sort_order).collect();
+        let mut sorted = orders.clone();
+        sorted.sort();
+        sorted.dedup();
+        assert_eq!(orders.len(), sorted.len(), "duplicate sort orders detected");
+    }
+
+    #[test]
+    fn every_route_has_unique_label() {
+        let labels: Vec<&str> = WHALE_ROUTES.iter().map(|r| r.label).collect();
+        let mut sorted = labels.clone();
+        sorted.sort();
+        sorted.dedup();
+        assert_eq!(labels.len(), sorted.len(), "duplicate labels detected");
+    }
+}
diff --git a/crates/tui/src/tui/widgets/footer.rs b/crates/tui/src/tui/widgets/footer.rs
index 01ac69f8..d049c0c8 100644
--- a/crates/tui/src/tui/widgets/footer.rs
+++ b/crates/tui/src/tui/widgets/footer.rs
@@ -152,6 +152,19 @@ pub fn footer_working_label(frame: u64, locale: Locale) -> String {
     out
 }
 
+/// Build a "⏳ shell running" chip span when a foreground shell command is
+/// active. Empty when no shell is running, which hides the chip entirely.
+#[must_use]
+pub fn footer_shell_chip(active: bool) -> Vec<Span<'static>> {
+    if !active {
+        return Vec::new();
+    }
+    vec![Span::styled(
+        "\u{23F3} shell running".to_string(),
+        Style::default().fg(palette::STATUS_WARNING),
+    )]
+}
+
 /// Build a "N agents" chip span list when there are sub-agents in flight.
 /// Empty list when N == 0 hides the chip entirely. Singular for N == 1
 /// reads naturally; plural otherwise. The pluralization template lives in
@@ -560,6 +573,17 @@ impl Renderable for FooterWidget {
             return;
         }
 
+        // Clear the whole footer row first so stale transcript glyphs from
+        // the previous frame cannot survive in cells this frame's spans do not
+        // touch (#2244).
+        for y in area.top()..area.bottom() {
+            for x in area.left()..area.right() {
+                buf[(x, y)]
+                    .set_symbol(" ")
+                    .set_style(Style::default().bg(self.props.footer_bg));
+            }
+        }
+
         let preview_left_spans = self.left_spans(available_width);
         let preview_left_width = span_width(&preview_left_spans);
         let right_budget = available_width
@@ -639,6 +663,8 @@ mod tests {
     use crate::palette;
     use crate::tui::app::{App, AppMode, TuiOptions};
     use ratatui::{
+        buffer::Buffer,
+        layout::Rect,
         style::{Color, Style},
         text::Span,
     };
@@ -1364,4 +1390,36 @@ mod tests {
         assert!(!rendered.contains("agent"));
         assert!(!rendered.contains("deepseek-v4-flash"));
     }
+
+    #[test]
+    fn render_clears_stale_cells_across_entire_footer_row() {
+        let app = make_app();
+        let widget = FooterWidget::new(idle_props_for(&app));
+        let area = Rect::new(0, 0, 48, 1);
+        let mut buf = Buffer::empty(area);
+
+        for x in area.x..area.x.saturating_add(area.width) {
+            buf[(x, area.y)]
+                .set_symbol("X")
+                .set_style(Style::default().fg(Color::Red).bg(Color::Blue));
+        }
+
+        widget.render(area, &mut buf);
+
+        let rendered: String = (area.x..area.x.saturating_add(area.width))
+            .map(|x| buf[(x, area.y)].symbol())
+            .collect();
+
+        assert!(
+            !rendered.contains('X'),
+            "footer render must clear stale row content before painting: {rendered:?}"
+        );
+        for x in area.x..area.x.saturating_add(area.width) {
+            assert_eq!(
+                buf[(x, area.y)].bg,
+                app.ui_theme.footer_bg,
+                "footer background should cover the full row"
+            );
+        }
+    }
 }
diff --git a/crates/tui/src/tui/widgets/mod.rs b/crates/tui/src/tui/widgets/mod.rs
index a8179769..7425a516 100644
--- a/crates/tui/src/tui/widgets/mod.rs
+++ b/crates/tui/src/tui/widgets/mod.rs
@@ -16,7 +16,8 @@ mod renderable;
 pub mod tool_card;
 
 pub use footer::{
-    FooterProps, FooterToast, FooterWidget, footer_agents_chip, footer_working_label,
+    FooterProps, FooterToast, FooterWidget, footer_agents_chip, footer_shell_chip,
+    footer_working_label,
 };
 pub use header::{HeaderData, HeaderWidget, header_status_indicator_frame};
 pub use renderable::Renderable;
@@ -155,6 +156,8 @@ impl ChatWidget {
                 &cell_revisions,
                 content_area.width.max(1),
                 render_options,
+                &app.folded_thinking,
+                None,
             );
         } else {
             // Slow path: clone non-collapsed cells into filtered vecs so
@@ -202,6 +205,8 @@ impl ChatWidget {
                 &filtered_revs,
                 content_area.width.max(1),
                 render_options,
+                &app.folded_thinking,
+                Some(&app.collapsed_cell_map),
             );
         }
 
@@ -473,7 +478,7 @@ impl<'a> ComposerWidget<'a> {
     /// backend's per-cell write cost makes the layout jitter visible
     /// even though the work is tiny on Unix terminals. See user
     /// feedback in v0.8.8 polish thread.
-    fn active_menu_reserved_rows(&self) -> usize {
+    pub fn active_menu_reserved_rows(&self) -> usize {
         let actual = self.active_menu_row_count();
         if actual == 0 {
             return 0;
@@ -534,8 +539,8 @@ impl Renderable for ComposerWidget<'_> {
         let input_rows_budget =
             composer_input_rows_budget(inner_area.height, menu_lines_for_budget);
         let content_width = usize::from(inner_area.width.max(1));
-        let (visible_lines, _cursor_row, _cursor_col) =
-            layout_input(input_text, input_cursor, content_width, input_rows_budget);
+        let (visible_lines, _cursor_row, _cursor_col, scroll_offset) =
+            layout_input_with_scroll(input_text, input_cursor, content_width, input_rows_budget);
         let is_draft_mode = input_text.contains('\n') || visible_lines.len() > 1;
         if has_panel {
             let border_color = if input_text.trim().is_empty() {
@@ -665,6 +670,26 @@ impl Renderable for ComposerWidget<'_> {
                 placeholder,
                 Style::default().fg(palette::TEXT_MUTED).italic(),
             )));
+        } else if let Some((sel_start, sel_end)) = self.app.selection_range() {
+            let line_ranges: Vec<(usize, usize)> =
+                wrap_input_lines_for_mouse(&self.app.input, content_width)
+                    .into_iter()
+                    .skip(scroll_offset)
+                    .take(visible_lines.len())
+                    .map(|(start, text)| (start, start + text.chars().count()))
+                    .collect();
+            for (line_text, (line_start, line_end)) in visible_lines.iter().zip(line_ranges.iter())
+            {
+                let spans = line_spans_with_selection(
+                    line_text,
+                    *line_start,
+                    *line_end,
+                    sel_start,
+                    sel_end,
+                    self.app.ui_theme.selection_bg,
+                );
+                input_lines.push(Line::from(spans));
+            }
         } else {
             for line in &visible_lines {
                 input_lines.push(Line::from(Span::styled(
@@ -1015,13 +1040,10 @@ impl Renderable for ComposerWidget<'_> {
 
 /// Codex-style full-screen approval takeover (#129).
 ///
-/// The widget reads its mutable state (selected option, staged
-/// confirmation) directly from the [`ApprovalView`] so the destructive
-/// variant can render its "Press Y again to confirm" banner without
-/// touching internal fields. Rendering reflows to fill most of the
-/// transcript area instead of a centered popup; on small terminals it
-/// falls back to a 65×22 card so existing snapshot tests still see a
-/// coherent layout.
+/// The widget reads its selected option and locale directly from the
+/// [`ApprovalView`]. Rendering reflows to fill most of the transcript
+/// area instead of a centered popup; on small terminals it falls back to
+/// a 65×22 card so existing snapshot tests still see a coherent layout.
 pub struct ApprovalWidget<'a> {
     request: &'a ApprovalRequest,
     view: &'a ApprovalView,
@@ -1038,8 +1060,8 @@ impl<'a> ApprovalWidget<'a> {
 /// terminal can hold.
 const APPROVAL_CARD_HORIZONTAL_PAD: u16 = 6;
 const APPROVAL_CARD_VERTICAL_PAD: u16 = 2;
-/// Minimum card height — anything tighter and the destructive variant's
-/// confirmation banner overlaps the option list.
+/// Minimum card height — anything tighter and the approval controls
+/// overlap the option list.
 const APPROVAL_CARD_MIN_HEIGHT: u16 = 18;
 /// Minimum card width — anything tighter makes approval copy wrap too
 /// aggressively on small terminals.
@@ -1164,120 +1186,49 @@ impl Renderable for ApprovalWidget<'_> {
         lines.push(Line::from(""));
 
         let options = approval_options_for(risk, locale);
-        let pending = self.view.pending_confirm();
 
         for (i, opt) in options.iter().enumerate() {
             let is_selected = i == self.view.selected();
-            let staged = pending.is_some_and(|p| p == opt.option);
             let label_color = if opt.dangerous {
                 palette_colors.accent
             } else {
                 palette::TEXT_BODY
             };
 
-            let row_style = if is_selected {
-                Style::default()
-                    .fg(palette::SELECTION_TEXT)
-                    .bg(palette::SELECTION_BG)
-            } else {
-                Style::default()
-            };
+            let option_style = approval_option_style(is_selected, label_color);
+            let shortcut_style = approval_option_style(is_selected, palette_colors.shortcut);
 
-            let mut spans = vec![
+            let spans = vec![
                 Span::raw("  "),
                 Span::styled(
                     format!("[{}] ", opt.key_hint),
-                    Style::default()
-                        .fg(palette_colors.shortcut)
-                        .add_modifier(Modifier::BOLD),
+                    shortcut_style.add_modifier(Modifier::BOLD),
                 ),
-                Span::styled(opt.label.to_string(), row_style.fg(label_color)),
+                Span::styled(opt.label.to_string(), option_style),
             ];
-            if staged {
-                spans.push(Span::raw("  "));
-                spans.push(Span::styled(
-                    staged_marker(locale),
-                    Style::default()
-                        .fg(palette_colors.accent)
-                        .add_modifier(Modifier::BOLD),
-                ));
-            }
             lines.push(Line::from(spans));
         }
 
-        // Variant-specific footer: benign nudges single-key approve;
-        // destructive shows either the standing prompt or the
-        // confirmation banner when an approve key has been staged.
+        // Footer: Enter commits the highlighted row; y/a/d remain direct
+        // shortcuts for users who do not want to move the selection.
         lines.push(Line::from(""));
-        match (risk, pending) {
-            (RiskLevel::Benign, _) => {
-                lines.push(Line::from(vec![
-                    Span::raw("  "),
-                    Span::styled(
-                        single_key_prefix(locale),
-                        Style::default().fg(palette::TEXT_HINT),
-                    ),
-                    Span::styled(
-                        single_key_value(locale),
-                        Style::default()
-                            .fg(palette_colors.accent)
-                            .add_modifier(Modifier::BOLD),
-                    ),
-                    Span::styled(
-                        footer_controls(locale),
-                        Style::default().fg(palette::TEXT_HINT),
-                    ),
-                ]));
-            }
-            (RiskLevel::Destructive, Some(opt)) => {
-                let again_key = match opt {
-                    crate::tui::approval::ApprovalOption::ApproveOnce => confirm_key_once(locale),
-                    crate::tui::approval::ApprovalOption::ApproveAlways => {
-                        confirm_key_always(locale)
-                    }
-                    _ => "Enter",
-                };
-                lines.push(Line::from(vec![
-                    Span::raw("  "),
-                    Span::styled(
-                        destructive_confirm_prefix(locale),
-                        Style::default()
-                            .fg(palette_colors.accent)
-                            .add_modifier(Modifier::BOLD),
-                    ),
-                    Span::styled(
-                        again_key.to_string(),
-                        Style::default()
-                            .fg(palette::DEEPSEEK_INK)
-                            .bg(palette_colors.accent)
-                            .add_modifier(Modifier::BOLD),
-                    ),
-                    Span::styled(
-                        destructive_confirm_suffix(locale),
-                        Style::default().fg(palette::TEXT_HINT),
-                    ),
-                ]));
-            }
-            (RiskLevel::Destructive, None) => {
-                lines.push(Line::from(vec![
-                    Span::raw("  "),
-                    Span::styled(
-                        two_key_prefix(locale),
-                        Style::default().fg(palette::TEXT_HINT),
-                    ),
-                    Span::styled(
-                        two_key_value(locale),
-                        Style::default()
-                            .fg(palette_colors.accent)
-                            .add_modifier(Modifier::BOLD),
-                    ),
-                    Span::styled(
-                        footer_controls(locale),
-                        Style::default().fg(palette::TEXT_HINT),
-                    ),
-                ]));
-            }
-        }
+        lines.push(Line::from(vec![
+            Span::raw("  "),
+            Span::styled(
+                selection_hint_prefix(locale),
+                Style::default().fg(palette::TEXT_HINT),
+            ),
+            Span::styled(
+                selection_hint_value(locale),
+                Style::default()
+                    .fg(palette_colors.accent)
+                    .add_modifier(Modifier::BOLD),
+            ),
+            Span::styled(
+                footer_controls(locale),
+                Style::default().fg(palette::TEXT_HINT),
+            ),
+        ]));
 
         let title = format!(
             " {} {} — {} ",
@@ -1375,6 +1326,21 @@ fn approval_palette(risk: RiskLevel) -> ApprovalColors {
     }
 }
 
+fn approval_selected_style() -> Style {
+    Style::default()
+        .fg(palette::SELECTION_TEXT)
+        .bg(palette::DEEPSEEK_BLUE)
+        .add_modifier(Modifier::BOLD)
+}
+
+fn approval_option_style(is_selected: bool, color: Color) -> Style {
+    if is_selected {
+        approval_selected_style()
+    } else {
+        Style::default().fg(color)
+    }
+}
+
 fn risk_badge_text(risk: RiskLevel, locale: Locale) -> &'static str {
     match (locale, risk) {
         (Locale::ZhHans, RiskLevel::Benign) => "审查",
@@ -1438,24 +1404,6 @@ fn label_params(locale: Locale) -> &'static str {
     }
 }
 
-fn staged_marker(locale: Locale) -> &'static str {
-    match locale {
-        Locale::ZhHans => "(待确认)",
-        _ => "(staged)",
-    }
-}
-
-fn single_key_prefix(locale: Locale) -> &'static str {
-    match locale {
-        Locale::ZhHans => "单键批准：",
-        _ => "Single key approves: ",
-    }
-}
-
-fn single_key_value(_locale: Locale) -> &'static str {
-    "Enter / 1 / y"
-}
-
 fn footer_controls(locale: Locale) -> &'static str {
     match locale {
         Locale::ZhHans => "  ·  v：完整参数  ·  Esc：终止",
@@ -1463,79 +1411,45 @@ fn footer_controls(locale: Locale) -> &'static str {
     }
 }
 
-fn destructive_confirm_prefix(locale: Locale) -> &'static str {
+fn selection_hint_prefix(locale: Locale) -> &'static str {
     match locale {
-        Locale::ZhHans => "确认破坏性操作：再次按 ",
-        _ => "Confirm destructive action — press ",
+        Locale::ZhHans => "选择：",
+        _ => "Choose: ",
     }
 }
 
-fn destructive_confirm_suffix(locale: Locale) -> &'static str {
+fn selection_hint_value(locale: Locale) -> &'static str {
     match locale {
-        Locale::ZhHans => " 执行；按其他键取消。",
-        _ => " again to commit, anything else cancels.",
-    }
-}
-
-fn confirm_key_once(locale: Locale) -> &'static str {
-    match locale {
-        Locale::ZhHans => "Enter 或 y",
-        _ => "Enter or y",
-    }
-}
-
-fn confirm_key_always(locale: Locale) -> &'static str {
-    match locale {
-        Locale::ZhHans => "Enter 或 a",
-        _ => "Enter or a",
-    }
-}
-
-fn two_key_prefix(locale: Locale) -> &'static str {
-    match locale {
-        Locale::ZhHans => "两次按键确认：",
-        _ => "Two keys to approve: ",
-    }
-}
-
-fn two_key_value(locale: Locale) -> &'static str {
-    match locale {
-        Locale::ZhHans => "先按 y/a，再按一次 y/a",
-        _ => "y/a then y/a again",
+        Locale::ZhHans => "Enter 执行选中项，或直接按 y/a/d",
+        _ => "Enter selected option, or press y/a/d directly",
     }
 }
 
 struct ApprovalOptionRow {
-    option: crate::tui::approval::ApprovalOption,
     label: &'static str,
     key_hint: &'static str,
     dangerous: bool,
 }
 
 fn approval_options_for(risk: RiskLevel, locale: Locale) -> [ApprovalOptionRow; 4] {
-    use crate::tui::approval::ApprovalOption as O;
     let dangerous = matches!(risk, RiskLevel::Destructive);
     [
         ApprovalOptionRow {
-            option: O::ApproveOnce,
             label: option_approve_once(locale),
             key_hint: "1 / y",
             dangerous,
         },
         ApprovalOptionRow {
-            option: O::ApproveAlways,
             label: option_approve_always(locale),
             key_hint: "2 / a",
             dangerous,
         },
         ApprovalOptionRow {
-            option: O::Deny,
             label: option_deny(locale),
             key_hint: "3 / d / n",
             dangerous: false,
         },
         ApprovalOptionRow {
-            option: O::Abort,
             label: option_abort(locale),
             key_hint: "Esc",
             dangerous: false,
@@ -1938,7 +1852,8 @@ fn vim_mode_style(mode: VimMode) -> Style {
 
 fn composer_top_right_chrome(app: &App, area_width: u16) -> Option<Line<'static>> {
     let receipt = app.active_receipt_text();
-    if !app.composer.vim_enabled && receipt.is_none() {
+    let session_title = app.session_title.as_deref();
+    if !app.composer.vim_enabled && receipt.is_none() && session_title.is_none() {
         return None;
     }
 
@@ -1977,18 +1892,39 @@ fn composer_top_right_chrome(app: &App, area_width: u16) -> Option<Line<'static>
         )));
     }
 
+    let mut spans: Vec<Span> = Vec::new();
     if app.composer.vim_enabled {
-        return Some(Line::from(Span::styled(
+        spans.push(Span::styled(
             truncate_display_width(app.composer.vim_mode.label(), max_width),
             vim_mode_style(app.composer.vim_mode),
-        )));
+        ));
+    }
+    if let Some(title) = session_title {
+        let used: usize = spans
+            .iter()
+            .map(|s| UnicodeWidthStr::width(s.content.as_ref()))
+            .sum();
+        let sep = if spans.is_empty() { 0 } else { 2 };
+        let remaining = max_width.saturating_sub(used + sep);
+        if remaining >= 4 {
+            if !spans.is_empty() {
+                spans.push(Span::raw("  "));
+            }
+            spans.push(Span::styled(
+                truncate_display_width(title, remaining),
+                Style::default().fg(palette::TEXT_MUTED),
+            ));
+        }
+    }
+    if spans.is_empty() {
+        None
+    } else {
+        Some(Line::from(spans))
     }
-
-    None
 }
 
 fn should_render_empty_state(app: &App) -> bool {
-    app.history.is_empty() && !app.is_loading && !app.is_compacting
+    app.history.is_empty() && !app.is_loading && !app.is_compacting && !app.is_purging
 }
 
 fn build_empty_state_lines(app: &App, area: Rect) -> Vec<Line<'static>> {
@@ -2017,7 +1953,8 @@ fn build_empty_state_lines(app: &App, area: Rect) -> Vec<Line<'static>> {
         )),
     ];
 
-    let top_padding = usize::from(area.height.saturating_sub(body.len() as u16) / 3);
+    // Keep the welcome block near the top of the chat pane (header is separate).
+    let top_padding = 2usize;
     let mut lines = Vec::new();
     for _ in 0..top_padding {
         lines.push(Line::from(""));
@@ -2026,7 +1963,7 @@ fn build_empty_state_lines(app: &App, area: Rect) -> Vec<Line<'static>> {
     lines
 }
 
-fn composer_input_rows_budget(inner_height: u16, extra_lines: usize) -> usize {
+pub fn composer_input_rows_budget(inner_height: u16, extra_lines: usize) -> usize {
     usize::from(inner_height).saturating_sub(extra_lines).max(1)
 }
 
@@ -2107,6 +2044,26 @@ pub(crate) struct SlashMenuEntry {
     pub alias_hint: Option<String>,
 }
 
+/// Check if all characters in `needle` appear in `haystack` in order
+/// (subsequence matching — fuzzy filtering).
+fn fuzzy_chars_in_order(needle: &str, haystack: &str) -> bool {
+    let mut chars = needle.chars();
+    let mut current = match chars.next() {
+        Some(c) => c,
+        None => return true,
+    };
+    for ch in haystack.chars() {
+        if ch == current {
+            if let Some(next) = chars.next() {
+                current = next;
+            } else {
+                return true;
+            }
+        }
+    }
+    false
+}
+
 pub(crate) fn slash_completion_hints(
     input: &str,
     limit: usize,
@@ -2125,61 +2082,121 @@ pub(crate) fn slash_completion_hints(
         return Vec::new();
     }
     let mut entries: Vec<SlashMenuEntry> = Vec::new();
+    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
+    let prefix_lower = prefix.to_ascii_lowercase();
+    let user_commands = if completing_skill_arg.is_none() {
+        commands::user_commands::load_user_commands(workspace)
+    } else {
+        Vec::new()
+    };
 
-    // Built-in commands + user-defined commands
-    // `all_command_names_matching` returns both; we resolve descriptions for
-    // built-in ones from the static registry and use a generic label for
-    // user-defined commands.
+    // ── Phase 1: prefix (starts_with) matches ─────────────────────────
+    // Highest priority — preserves existing exact-prefix completion.
     if completing_skill_arg.is_none() {
-        let prefix_lower = prefix.to_ascii_lowercase();
-        for name in commands::all_command_names_matching(prefix, workspace) {
+        for name in all_command_names_matching_loaded(prefix, &user_commands) {
+            seen.insert(name.clone());
             let command_key = name.trim_start_matches('/');
-            let (description, alias_hint) =
-                if let Some(info) = commands::get_command_info(command_key) {
-                    // Detect matching alias: if the user typed via pinyin rather
-                    // than the canonical name, record which alias matched.
-                    let hint = if !command_key.to_ascii_lowercase().starts_with(&prefix_lower) {
-                        info.aliases
-                            .iter()
-                            .find(|a| a.to_ascii_lowercase().starts_with(&prefix_lower))
-                            .map(|a| a.to_string())
-                    } else {
-                        None
-                    };
-                    let desc = if info.aliases.is_empty() {
-                        info.description_for(locale).to_string()
-                    } else {
-                        format!(
-                            "{}  (aliases: {})",
-                            info.description_for(locale),
-                            info.aliases
-                                .iter()
-                                .map(|a| format!("/{a}"))
-                                .collect::<Vec<_>>()
-                                .join(", ")
-                        )
-                    };
-                    (desc, hint)
-                } else {
-                    (String::from("User-defined command"), None)
-                };
-            entries.push(SlashMenuEntry {
-                name,
-                description,
-                is_skill: false,
-                alias_hint,
-            });
+            push_command_entry(
+                &mut entries,
+                &name,
+                command_key,
+                &prefix_lower,
+                locale,
+                &user_commands,
+            );
         }
     }
 
-    // Cached skills are arguments to `/skill`, not top-level commands. Keep
-    // the top-level slash menu focused on commands and expand skills only
-    // after the user has selected the skill command.
-    let prefix_lower = completing_skill_arg.unwrap_or(prefix).to_ascii_lowercase();
+    // ── Phase 2: contains (substring) matches ─────────────────────────
+    // Medium priority — broader catching.
+    if completing_skill_arg.is_none() {
+        for cmd in commands::COMMANDS {
+            let name = format!("/{}", cmd.name);
+            if seen.contains(&name) {
+                continue;
+            }
+            let cmd_lower = cmd.name.to_ascii_lowercase();
+            let alias_match = cmd
+                .aliases
+                .iter()
+                .any(|a| a.to_ascii_lowercase().contains(&prefix_lower));
+            if cmd_lower.contains(&prefix_lower) || alias_match {
+                seen.insert(name.clone());
+                push_command_entry(
+                    &mut entries,
+                    &name,
+                    cmd.name,
+                    &prefix_lower,
+                    locale,
+                    &user_commands,
+                );
+            }
+        }
+    }
+
+    // ── Phase 3: fuzzy subsequence matches ────────────────────────────
+    // Lowest priority — characters in order, not necessarily consecutive.
+    if completing_skill_arg.is_none() {
+        for cmd in commands::COMMANDS {
+            let name = format!("/{}", cmd.name);
+            if seen.contains(&name) {
+                continue;
+            }
+            let cmd_lower = cmd.name.to_ascii_lowercase();
+            let alias_match = cmd
+                .aliases
+                .iter()
+                .any(|a| fuzzy_chars_in_order(&prefix_lower, &a.to_ascii_lowercase()));
+            if fuzzy_chars_in_order(&prefix_lower, &cmd_lower) || alias_match {
+                seen.insert(name.clone());
+                push_command_entry(
+                    &mut entries,
+                    &name,
+                    cmd.name,
+                    &prefix_lower,
+                    locale,
+                    &user_commands,
+                );
+            }
+        }
+    }
+
+    // ── Skills (only after user has typed `/skill `) ──────────────────
+    let skill_prefix = completing_skill_arg.unwrap_or(prefix).to_ascii_lowercase();
     if completing_skill_arg.is_some() {
         for (skill_name, skill_desc) in cached_skills {
             let skill_name_lower = skill_name.to_ascii_lowercase();
-            if skill_name_lower.starts_with(&prefix_lower) {
+            if skill_name_lower.starts_with(&skill_prefix) {
+                entries.push(SlashMenuEntry {
+                    name: format!("/skill {skill_name}"),
+                    description: skill_desc.clone(),
+                    is_skill: true,
+                    alias_hint: None,
+                });
+            }
+        }
+        // Skills: contains fuzzy fallback
+        for (skill_name, skill_desc) in cached_skills {
+            let skill_name_lower = skill_name.to_ascii_lowercase();
+            if skill_name_lower.contains(&skill_prefix)
+                && !entries
+                    .iter()
+                    .any(|e| e.name == format!("/skill {skill_name}"))
+            {
+                entries.push(SlashMenuEntry {
+                    name: format!("/skill {skill_name}"),
+                    description: skill_desc.clone(),
+                    is_skill: true,
+                    alias_hint: None,
+                });
+            }
+        }
+        for (skill_name, skill_desc) in cached_skills {
+            let skill_name_lower = skill_name.to_ascii_lowercase();
+            if !skill_name_lower.starts_with(&skill_prefix)
+                && !skill_name_lower.contains(&skill_prefix)
+                && fuzzy_chars_in_order(&skill_prefix, &skill_name_lower)
+            {
                 entries.push(SlashMenuEntry {
                     name: format!("/skill {skill_name}"),
                     description: skill_desc.clone(),
@@ -2232,12 +2249,114 @@ pub(crate) fn slash_completion_hints(
     entries.into_iter().take(limit).collect()
 }
 
+fn all_command_names_matching_loaded(
+    prefix: &str,
+    user_commands: &[(String, String)],
+) -> Vec<String> {
+    let prefix = prefix.strip_prefix('/').unwrap_or(prefix).to_lowercase();
+    let mut result: Vec<String> = commands::COMMANDS
+        .iter()
+        .filter(|cmd| {
+            cmd.name.starts_with(&prefix) || cmd.aliases.iter().any(|a| a.starts_with(&prefix))
+        })
+        .map(|cmd| format!("/{}", cmd.name))
+        .collect();
+
+    result.extend(
+        user_commands
+            .iter()
+            .filter(|(name, _)| name.starts_with(&prefix))
+            .map(|(name, _)| format!("/{name}")),
+    );
+
+    result.sort();
+    result.dedup();
+    result
+}
+
+/// Push a built-in command entry to the slash menu, resolving description
+/// and alias hints.
+fn push_command_entry(
+    entries: &mut Vec<SlashMenuEntry>,
+    name: &str,
+    command_key: &str,
+    prefix_lower: &str,
+    locale: crate::localization::Locale,
+    user_commands: &[(String, String)],
+) {
+    let (description, alias_hint) = if let Some(info) = commands::get_command_info(command_key) {
+        let hint = if !command_key.to_ascii_lowercase().starts_with(prefix_lower) {
+            info.aliases
+                .iter()
+                .find(|a| {
+                    a.to_ascii_lowercase().starts_with(prefix_lower)
+                        || a.to_ascii_lowercase().contains(prefix_lower)
+                        || fuzzy_chars_in_order(prefix_lower, &a.to_ascii_lowercase())
+                })
+                .map(|a| a.to_string())
+        } else {
+            None
+        };
+        let desc = if info.aliases.is_empty() {
+            info.description_for(locale).to_string()
+        } else {
+            format!(
+                "{}  (aliases: {})",
+                info.description_for(locale),
+                info.aliases
+                    .iter()
+                    .map(|a| format!("/{a}"))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            )
+        };
+        (desc, hint)
+    } else {
+        let mut description = String::from("User-defined command");
+        let mut argument_hint = None;
+        if let Some((_, content)) = user_commands.iter().find(|(key, _)| key == command_key) {
+            let (metadata, _) = commands::user_commands::parse_frontmatter(content);
+            for (key, value) in metadata {
+                match key.as_str() {
+                    "description" => description = value,
+                    "argument-hint" => argument_hint = Some(value),
+                    _ => {}
+                }
+            }
+        }
+        if let Some(hint) = argument_hint {
+            if !hint.trim().is_empty() {
+                description.push_str("  ");
+                description.push_str(hint.trim());
+            }
+        }
+        (description, None)
+    };
+    entries.push(SlashMenuEntry {
+        name: name.to_string(),
+        description,
+        is_skill: false,
+        alias_hint,
+    });
+}
+
 fn layout_input(
     input: &str,
     cursor: usize,
     width: usize,
     max_height: usize,
 ) -> (Vec<String>, usize, usize) {
+    let (visible, visible_cursor_row, visible_cursor_col, _) =
+        layout_input_with_scroll(input, cursor, width, max_height);
+    (visible, visible_cursor_row, visible_cursor_col)
+}
+
+pub fn layout_input_with_scroll(
+    input: &str,
+    cursor: usize,
+    width: usize,
+    max_height: usize,
+) -> (Vec<String>, usize, usize, usize) {
     let mut lines = wrap_input_lines(input, width);
     if lines.is_empty() {
         lines.push(String::new());
@@ -2263,6 +2382,7 @@ fn layout_input(
         visible,
         visible_cursor_row,
         cursor_col.min(width.saturating_sub(1)),
+        start,
     )
 }
 
@@ -2329,6 +2449,34 @@ fn wrap_input_lines(input: &str, width: usize) -> Vec<String> {
     lines
 }
 
+/// For mouse coordinate mapping: returns (char_start_of_line, line_text) pairs
+/// matching the wrapping produced by `wrap_input_lines`.
+pub fn wrap_input_lines_for_mouse(input: &str, width: usize) -> Vec<(usize, String)> {
+    if input.is_empty() || width == 0 {
+        return vec![(0, String::new())];
+    }
+
+    let mut result = Vec::new();
+    let mut char_idx = 0usize;
+
+    for raw_line in input.split('\n') {
+        if raw_line.is_empty() {
+            result.push((char_idx, String::new()));
+            char_idx += 1; // the '\n'
+            continue;
+        }
+        let wrapped = wrap_text(raw_line, width);
+        for wrapped_line in &wrapped {
+            let line_char_len: usize = wrapped_line.chars().count();
+            result.push((char_idx, wrapped_line.clone()));
+            char_idx += line_char_len;
+        }
+        char_idx += 1; // the '\n'
+    }
+
+    result
+}
+
 fn wrap_text(text: &str, width: usize) -> Vec<String> {
     if width == 0 {
         return vec![text.to_string()];
@@ -2370,6 +2518,56 @@ fn wrap_text(text: &str, width: usize) -> Vec<String> {
     lines
 }
 
+fn line_spans_with_selection<'a>(
+    line: &'a str,
+    line_start: usize,
+    line_end: usize,
+    sel_start: usize,
+    sel_end: usize,
+    highlight_bg: Color,
+) -> Vec<Span<'a>> {
+    let normal_style = Style::default().fg(palette::TEXT_PRIMARY);
+    let sel_style = Style::default().fg(palette::TEXT_PRIMARY).bg(highlight_bg);
+
+    // No overlap between this line and the selection
+    if line_end <= sel_start || line_start >= sel_end {
+        return vec![Span::styled(line, normal_style)];
+    }
+
+    let local_sel_start = sel_start.saturating_sub(line_start);
+    let local_sel_end = sel_end.min(line_end).saturating_sub(line_start);
+
+    // Build a Vec of byte offsets for each char boundary, plus one past the end.
+    let mut byte_offsets: Vec<usize> = line.char_indices().map(|(i, _)| i).collect();
+    byte_offsets.push(line.len());
+
+    let b0 = byte_offsets
+        .get(local_sel_start)
+        .copied()
+        .unwrap_or(line.len());
+    let b1 = byte_offsets
+        .get(local_sel_end)
+        .copied()
+        .unwrap_or(line.len());
+
+    let mut spans = Vec::with_capacity(3);
+
+    // Text before selection
+    if b0 > 0 {
+        spans.push(Span::styled(&line[..b0], normal_style));
+    }
+    // Selected text
+    if b1 > b0 {
+        spans.push(Span::styled(&line[b0..b1], sel_style));
+    }
+    // Text after selection
+    if b1 < line.len() {
+        spans.push(Span::styled(&line[b1..], normal_style));
+    }
+
+    spans
+}
+
 #[cfg(test)]
 mod tests {
     use super::{
@@ -2377,7 +2575,8 @@ mod tests {
         SlashMenuEntry, apply_selection_to_line, build_empty_state_lines, composer_height,
         composer_max_height, composer_min_input_rows, composer_top_padding, compute_takeover_area,
         cursor_row_col, layout_input, pad_lines_to_bottom, placeholder_visual_lines,
-        should_render_empty_state, slash_completion_hints, wrap_input_lines, wrap_text,
+        push_command_entry, should_render_empty_state, slash_completion_hints, wrap_input_lines,
+        wrap_text,
     };
     use crate::config::{ApiProvider, Config};
     use crate::localization::Locale;
@@ -2637,6 +2836,80 @@ mod tests {
         assert!(!hints.iter().any(|hint| hint.name == "/codewhale"));
     }
 
+    #[test]
+    fn slash_completion_hints_use_user_command_frontmatter_description() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let commands_dir = tmp.path().join(".deepseek").join("commands");
+        std::fs::create_dir_all(&commands_dir).unwrap();
+        std::fs::write(
+            commands_dir.join("git-scan.md"),
+            "---\ndescription: Scan nested git repositories\n---\nscan",
+        )
+        .unwrap();
+
+        let hints = slash_completion_hints(
+            "/git",
+            128,
+            &[],
+            Locale::En,
+            Some(tmp.path()),
+            ApiProvider::Deepseek,
+        );
+        let entry = hints
+            .iter()
+            .find(|hint| hint.name == "/git-scan")
+            .expect("custom command should be present");
+        assert_eq!(entry.description, "Scan nested git repositories");
+    }
+
+    #[test]
+    fn slash_completion_hints_use_user_command_argument_hint() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let commands_dir = tmp.path().join(".deepseek").join("commands");
+        std::fs::create_dir_all(&commands_dir).unwrap();
+        std::fs::write(
+            commands_dir.join("deploy.md"),
+            "---\ndescription: Deploy target\nargument-hint: <env>\n---\ndeploy",
+        )
+        .unwrap();
+
+        let hints = slash_completion_hints(
+            "/deploy",
+            128,
+            &[],
+            Locale::En,
+            Some(tmp.path()),
+            ApiProvider::Deepseek,
+        );
+        let entry = hints
+            .iter()
+            .find(|hint| hint.name == "/deploy")
+            .expect("custom command should be present");
+        assert_eq!(entry.description, "Deploy target  <env>");
+    }
+
+    #[test]
+    fn review_regression_push_command_entry_uses_preloaded_user_command_frontmatter() {
+        let user_commands = vec![(
+            "deploy".to_string(),
+            "---\ndescription: Deploy target\nargument-hint: <env>\n---\ndeploy".to_string(),
+        )];
+        let mut entries = Vec::new();
+
+        push_command_entry(
+            &mut entries,
+            "/deploy",
+            "deploy",
+            "deploy",
+            Locale::En,
+            &user_commands,
+        );
+
+        assert_eq!(entries.len(), 1);
+        assert_eq!(entries[0].name, "/deploy");
+        assert_eq!(entries[0].description, "Deploy target  <env>");
+    }
+
     #[test]
     fn slash_completion_hints_hide_skills_from_top_level_menu() {
         let cached_skills = vec![
@@ -2882,11 +3155,10 @@ mod tests {
     }
 
     #[test]
-    fn composer_border_does_not_render_session_title() {
+    fn composer_border_renders_session_title() {
         let mut app = create_test_app();
         app.composer_density = ComposerDensity::Comfortable;
-        app.session_title =
-            Some("hello could you please take a look at codewhale-tui and all changes".to_string());
+        app.session_title = Some("my-session".to_string());
         let slash_menu_entries = Vec::<SlashMenuEntry>::new();
         let mention_menu_entries = Vec::<String>::new();
         let widget = ComposerWidget::new(&app, 5, &slash_menu_entries, &mention_menu_entries);
@@ -2902,8 +3174,7 @@ mod tests {
         let rendered = buffer_text(&buf, area);
 
         assert!(rendered.contains("Composer"));
-        assert!(!rendered.contains("codewhale-tui"));
-        assert!(!rendered.contains("hello could you"));
+        assert!(rendered.contains("my-session"));
     }
 
     #[test]
@@ -3479,6 +3750,43 @@ mod tests {
         }
     }
 
+    #[test]
+    fn approval_selected_destructive_option_uses_contrasting_highlight() {
+        let request = crate::tui::approval::ApprovalRequest::new(
+            "approval-1",
+            "exec_shell",
+            "Run git commit",
+            &serde_json::json!({ "command": "git commit -m fix" }),
+            "exec_shell:git commit",
+        );
+        let view = crate::tui::approval::ApprovalView::new(request.clone());
+        let widget = ApprovalWidget::new(&request, &view);
+        let area = Rect::new(0, 0, 100, 30);
+        let mut buf = Buffer::empty(area);
+
+        widget.render(area, &mut buf);
+
+        let selected_row = (area.y..area.y.saturating_add(area.height))
+            .find(|&y| {
+                (area.x..area.x.saturating_add(area.width))
+                    .any(|x| buf[(x, y)].bg == palette::DEEPSEEK_BLUE)
+            })
+            .expect("selected approval row should use blue background");
+        let highlighted_cells = (area.x..area.x.saturating_add(area.width))
+            .filter(|&x| {
+                let cell = &buf[(x, selected_row)];
+                !cell.symbol().trim().is_empty()
+                    && cell.bg == palette::DEEPSEEK_BLUE
+                    && cell.fg == palette::SELECTION_TEXT
+            })
+            .count();
+
+        assert!(
+            highlighted_cells >= 4,
+            "selected destructive option should render visible blue/white text"
+        );
+    }
+
     /// Regression for issue #65: after `App::handle_resize`, the chat widget
     /// must produce a clean render at the new width — no stale wrapping,
     /// no panic, no content exceeding the requested width. Cycling through
diff --git a/crates/tui/src/tui/workspace_context.rs b/crates/tui/src/tui/workspace_context.rs
index 4f9e44aa..cfe04618 100644
--- a/crates/tui/src/tui/workspace_context.rs
+++ b/crates/tui/src/tui/workspace_context.rs
@@ -107,6 +107,11 @@ fn collect(workspace: &Path) -> Option<String> {
     Some(format!("{branch} | {status}"))
 }
 
+pub(crate) fn branch_from_context(context: &str) -> Option<&str> {
+    let (branch, _) = context.rsplit_once(" | ")?;
+    (!branch.is_empty()).then_some(branch)
+}
+
 pub(super) fn branch(workspace: &Path) -> Option<String> {
     let branch = run_git(workspace, &["rev-parse", "--abbrev-ref", "HEAD"]).ok()?;
     let branch = branch.trim().to_string();
diff --git a/crates/tui/src/utils.rs b/crates/tui/src/utils.rs
index a260e1d5..15c23199 100644
--- a/crates/tui/src/utils.rs
+++ b/crates/tui/src/utils.rs
@@ -259,7 +259,17 @@ fn write_panic_dump(
     let home = dirs::home_dir().ok_or_else(|| {
         std::io::Error::new(std::io::ErrorKind::NotFound, "home directory not found")
     })?;
-    let crash_dir = home.join(".deepseek").join("crashes");
+    // Prefer .codewhale, fall back to .deepseek
+    let crash_dir = home.join(".codewhale").join("crashes");
+    if !crash_dir.exists() {
+        // Try legacy path for reading, but prefer new for writing
+        let _ = std::fs::create_dir_all(&crash_dir);
+    }
+    let crash_dir = if crash_dir.exists() {
+        crash_dir
+    } else {
+        home.join(".deepseek").join("crashes")
+    };
     write_panic_dump_to(&crash_dir, name, location, message)
 }
 
diff --git a/crates/tui/src/vision/tools.rs b/crates/tui/src/vision/tools.rs
index bfce551d..41cc41c1 100644
--- a/crates/tui/src/vision/tools.rs
+++ b/crates/tui/src/vision/tools.rs
@@ -13,6 +13,8 @@ use crate::tools::spec::{
     ToolCapability, ToolContext, ToolError, ToolResult, ToolSpec, required_str,
 };
 
+const DEFAULT_VISION_MAX_OUTPUT_TOKENS: u32 = 4096;
+
 pub struct ImageAnalyzeTool {
     config: VisionModelConfig,
     client: reqwest::Client,
@@ -67,6 +69,59 @@ impl ImageAnalyzeTool {
     fn api_key(&self) -> String {
         self.config.api_key.clone().unwrap_or_default()
     }
+
+    fn is_xiaomi_mimo_model(model: &str) -> bool {
+        let normalized = model.trim().to_ascii_lowercase();
+        let normalized = normalized.strip_prefix("xiaomi/").unwrap_or(&normalized);
+        normalized.starts_with("mimo-")
+    }
+
+    fn uses_max_completion_tokens(config: &VisionModelConfig) -> bool {
+        if Self::is_xiaomi_mimo_model(&config.model) {
+            return true;
+        }
+
+        let base_url = config.base_url.as_deref().unwrap_or_default();
+        let Ok(url) = reqwest::Url::parse(base_url) else {
+            return false;
+        };
+        let Some(domain) = url.domain() else {
+            return false;
+        };
+
+        domain.eq_ignore_ascii_case("xiaomimimo.com")
+            || domain.to_ascii_lowercase().ends_with(".xiaomimimo.com")
+    }
+
+    fn request_payload(&self, prompt: &str, image_data: &str, mime_type: &str) -> Value {
+        let mut payload = json!({
+            "model": self.config.model,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": prompt},
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": format!("data:{};base64,{}", mime_type, image_data)
+                            }
+                        }
+                    ]
+                }
+            ],
+            "temperature": 0.7
+        });
+
+        let token_limit_field = if Self::uses_max_completion_tokens(&self.config) {
+            "max_completion_tokens"
+        } else {
+            "max_tokens"
+        };
+        payload[token_limit_field] = json!(DEFAULT_VISION_MAX_OUTPUT_TOKENS);
+
+        payload
+    }
 }
 
 #[async_trait]
@@ -122,25 +177,7 @@ impl ToolSpec for ImageAnalyzeTool {
         let resolved_path = context.workspace.join(image_path_buf);
         let (image_data, mime_type) = Self::read_image_file(&resolved_path).await?;
 
-        let payload = json!({
-            "model": self.config.model,
-            "messages": [
-                {
-                    "role": "user",
-                    "content": [
-                        {"type": "text", "text": prompt},
-                        {
-                            "type": "image_url",
-                            "image_url": {
-                                "url": format!("data:{};base64,{}", mime_type, image_data)
-                            }
-                        }
-                    ]
-                }
-            ],
-            "max_tokens": 4096,
-            "temperature": 0.7
-        });
+        let payload = self.request_payload(prompt, &image_data, &mime_type);
 
         let url = format!("{}/chat/completions", self.base_url());
         let api_key = self.api_key();
@@ -262,6 +299,51 @@ mod tests {
         assert!(err.to_string().contains("Unsupported image format"));
     }
 
+    #[test]
+    fn generic_vision_payload_uses_max_tokens() {
+        let tool = ImageAnalyzeTool::new(fake_config());
+
+        let payload = tool.request_payload("describe", "abc123", "image/png");
+
+        assert_eq!(
+            payload.get("max_tokens").and_then(Value::as_u64),
+            Some(u64::from(DEFAULT_VISION_MAX_OUTPUT_TOKENS))
+        );
+        assert!(payload.get("max_completion_tokens").is_none());
+    }
+
+    #[test]
+    fn xiaomi_mimo_vision_payload_uses_max_completion_tokens() {
+        let mut config = fake_config();
+        config.model = "mimo-v2.5".to_string();
+        config.base_url = Some("https://api.xiaomimimo.com/v1".to_string());
+        let tool = ImageAnalyzeTool::new(config);
+
+        let payload = tool.request_payload("describe", "abc123", "image/png");
+
+        assert_eq!(
+            payload.get("max_completion_tokens").and_then(Value::as_u64),
+            Some(u64::from(DEFAULT_VISION_MAX_OUTPUT_TOKENS))
+        );
+        assert!(payload.get("max_tokens").is_none());
+    }
+
+    #[test]
+    fn xiaomi_mimo_vision_payload_uses_max_completion_tokens_with_custom_proxy() {
+        let mut config = fake_config();
+        config.model = "mimo-v2.5".to_string();
+        config.base_url = Some("https://vision-proxy.example.invalid/v1".to_string());
+        let tool = ImageAnalyzeTool::new(config);
+
+        let payload = tool.request_payload("describe", "abc123", "image/png");
+
+        assert_eq!(
+            payload.get("max_completion_tokens").and_then(Value::as_u64),
+            Some(u64::from(DEFAULT_VISION_MAX_OUTPUT_TOKENS))
+        );
+        assert!(payload.get("max_tokens").is_none());
+    }
+
     #[tokio::test]
     async fn execute_rejects_absolute_path() {
         // Trust-boundary pin: image_path must stay inside the workspace
diff --git a/crates/tui/src/working_set.rs b/crates/tui/src/working_set.rs
index 2b1cc2bf..655d1f15 100644
--- a/crates/tui/src/working_set.rs
+++ b/crates/tui/src/working_set.rs
@@ -7,6 +7,9 @@
 //! - pinned message indices that compaction should preserve
 
 use crate::models::{ContentBlock, Message};
+use crate::workspace_discovery::{
+    DISCOVERY_ALWAYS_DIRS, path_is_excluded_from_discovery, should_skip_unignored_discovery_entry,
+};
 use ignore::WalkBuilder;
 use regex::Regex;
 use serde::{Deserialize, Serialize};
@@ -269,32 +272,6 @@ const COMPLETIONS_WALK_DEPTH: usize = 6;
 /// above the actual entry count and the cap is a no-op.
 const FILE_INDEX_MAX_ENTRIES: usize = 50_000;
 
-/// Directories that must remain discoverable for `@`-mention completion and
-/// fuzzy file resolution even when excluded by `.gitignore`. AI-tool
-/// convention directories (`.deepseek/`, `.cursor/`, `.claude/`, `.agents/`)
-/// are routinely gitignored, but users need to `@`-mention files inside them.
-const DISCOVERY_ALWAYS_DIRS: &[&str] = &[".deepseek", ".cursor", ".claude", ".agents"];
-
-/// Subdirectories under `DISCOVERY_ALWAYS_DIRS` that must NOT be indexed
-/// even when the parent dir is walked with gitignore disabled. These are
-/// large, machine-generated, or sensitive paths that would blow up the
-/// walker (e.g. `.deepseek/snapshots/` — the snapshot side repo that
-/// #1112 caps at 500 MB; indexing it would trigger the same OOM/hang
-/// the cap was built to prevent).
-const DISCOVERY_EXCLUDED_SUBDIRS: &[&str] = &[".deepseek/snapshots"];
-
-/// Check whether a path resolved against `walk_root` falls inside any
-/// `DISCOVERY_EXCLUDED_SUBDIRS` entry. Used to keep the snapshot side
-/// repo (`.deepseek/snapshots/`) out of the completion/index walk.
-fn path_is_excluded_from_discovery(walk_root: &Path, path: &Path) -> bool {
-    for excluded in DISCOVERY_EXCLUDED_SUBDIRS {
-        if path.starts_with(walk_root.join(excluded)) {
-            return true;
-        }
-    }
-    false
-}
-
 /// Configure a `WalkBuilder` for workspace discovery: hidden files, no
 /// symlink following, depth-limited, custom `.deepseekignore` honored,
 /// and gitignore overrides for AI-tool dot-directories so `@`-completion
@@ -494,7 +471,10 @@ fn local_reference_paths(root: &Path, limit: usize) -> Vec<PathBuf> {
         .git_global(false)
         .git_exclude(false);
     let _ = builder.add_custom_ignore_filename(".deepseekignore");
-    builder.filter_entry(|entry| !should_skip_local_reference_dir(entry.path()));
+    let root_for_filter = root.to_path_buf();
+    builder.filter_entry(move |entry| {
+        !should_skip_unignored_discovery_entry(&root_for_filter, entry.path())
+    });
 
     for entry in builder.build().flatten() {
         if out.len() >= limit {
@@ -514,25 +494,6 @@ fn local_reference_paths(root: &Path, limit: usize) -> Vec<PathBuf> {
     out
 }
 
-fn should_skip_local_reference_dir(path: &Path) -> bool {
-    let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
-        return false;
-    };
-    matches!(
-        name,
-        ".git"
-            | "target"
-            | "node_modules"
-            | ".venv"
-            | "venv"
-            | "env"
-            | "dist"
-            | "build"
-            | "__pycache__"
-            | ".ruff_cache"
-    )
-}
-
 impl Clone for Workspace {
     fn clone(&self) -> Self {
         // Don't carry the cached file_index — clones get a fresh OnceLock so
@@ -1523,6 +1484,82 @@ mod tests {
         );
     }
 
+    #[test]
+    fn workspace_completions_skip_hidden_worktrees_and_build_bulk() {
+        let tmp = TempDir::new().unwrap();
+        let root = tmp.path();
+        std::fs::write(root.join(".gitignore"), ".worktrees/\n.generated/\n").unwrap();
+
+        std::fs::create_dir_all(root.join(".worktrees/release/src")).unwrap();
+        std::fs::write(
+            root.join(".worktrees/release/src/worktree-only.rs"),
+            "fn main() {}",
+        )
+        .unwrap();
+        std::fs::create_dir_all(root.join(".worktrees/release/target/debug")).unwrap();
+        std::fs::write(
+            root.join(".worktrees/release/target/debug/generated.o"),
+            "object",
+        )
+        .unwrap();
+
+        std::fs::create_dir_all(root.join(".claude/worktrees/agent/src")).unwrap();
+        std::fs::write(
+            root.join(".claude/worktrees/agent/src/agent-only.md"),
+            "agent note",
+        )
+        .unwrap();
+        std::fs::create_dir_all(root.join(".claude/commands")).unwrap();
+        std::fs::write(root.join(".claude/commands/keep.md"), "command").unwrap();
+
+        std::fs::create_dir_all(root.join(".generated/specs")).unwrap();
+        std::fs::write(root.join(".generated/specs/device-layout.md"), "layout").unwrap();
+
+        let ws = Workspace::with_cwd(root.to_path_buf(), Some(root.to_path_buf()));
+
+        let worktree_entries = ws.completions(".worktrees", 32);
+        assert!(
+            worktree_entries
+                .iter()
+                .all(|entry| !entry.starts_with(".worktrees/")),
+            "hidden release worktrees must stay out of completions: {worktree_entries:?}",
+        );
+
+        let claude_worktree_entries = ws.completions(".claude/worktrees", 32);
+        assert!(
+            claude_worktree_entries
+                .iter()
+                .all(|entry| !entry.starts_with(".claude/worktrees/")),
+            ".claude/worktrees must stay out of completions: {claude_worktree_entries:?}",
+        );
+
+        let generated_entries = ws.completions(".generated/specs", 32);
+        assert!(
+            generated_entries
+                .iter()
+                .any(|entry| entry == ".generated/specs/device-layout.md"),
+            "explicit user-generated hidden folders should still complete: {generated_entries:?}",
+        );
+
+        let command_entries = ws.completions(".claude/commands", 32);
+        assert!(
+            command_entries
+                .iter()
+                .any(|entry| entry == ".claude/commands/keep.md"),
+            "normal .claude command files should still complete: {command_entries:?}",
+        );
+
+        assert!(
+            ws.resolve("worktree-only.rs").is_err(),
+            "fuzzy resolution must not index files from hidden release worktrees"
+        );
+        assert!(
+            ws.resolve("agent-only.md").is_err(),
+            "fuzzy resolution must not index files from .claude/worktrees"
+        );
+        assert!(ws.resolve("keep.md").is_ok());
+    }
+
     #[test]
     fn fuzzy_index_resolves_hidden_and_ignored_files_except_deepseekignored() {
         let tmp = TempDir::new().unwrap();
diff --git a/crates/tui/src/workspace_discovery.rs b/crates/tui/src/workspace_discovery.rs
new file mode 100644
index 00000000..ac41c33d
--- /dev/null
+++ b/crates/tui/src/workspace_discovery.rs
@@ -0,0 +1,53 @@
+//! Shared workspace discovery filters for UI path pickers and mentions.
+
+use std::path::Path;
+
+/// Directories that must remain discoverable for `@`-mention completion and
+/// fuzzy file resolution even when excluded by `.gitignore`.
+pub(crate) const DISCOVERY_ALWAYS_DIRS: &[&str] = &[".deepseek", ".cursor", ".claude", ".agents"];
+
+/// Root-relative directories that are too large or generated to discover
+/// with gitignore disabled. Exact user-specified paths may still resolve.
+const DISCOVERY_EXCLUDED_SUBDIRS: &[&str] =
+    &[".deepseek/snapshots", ".worktrees", ".claude/worktrees"];
+
+/// Directory basenames that should not be traversed by fallback discovery
+/// walks that deliberately disable gitignore.
+const DISCOVERY_EXCLUDED_DIR_NAMES: &[&str] = &[
+    ".git",
+    "target",
+    "node_modules",
+    ".venv",
+    "venv",
+    "env",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    "coverage",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+];
+
+/// Check whether `path` is under a root-relative excluded discovery subtree.
+pub(crate) fn path_is_excluded_from_discovery(walk_root: &Path, path: &Path) -> bool {
+    DISCOVERY_EXCLUDED_SUBDIRS
+        .iter()
+        .any(|excluded| path.starts_with(walk_root.join(excluded)))
+}
+
+/// Filter for walks that turn off gitignore to surface explicit hidden paths.
+pub(crate) fn should_skip_unignored_discovery_entry(walk_root: &Path, path: &Path) -> bool {
+    if path == walk_root {
+        return false;
+    }
+
+    if path_is_excluded_from_discovery(walk_root, path) {
+        return true;
+    }
+
+    path.file_name()
+        .and_then(|name| name.to_str())
+        .is_some_and(|name| DISCOVERY_EXCLUDED_DIR_NAMES.contains(&name))
+}
diff --git a/crates/tui/tests/eval_harness.rs b/crates/tui/tests/eval_harness.rs
index 8fb7485a..00a5d26b 100644
--- a/crates/tui/tests/eval_harness.rs
+++ b/crates/tui/tests/eval_harness.rs
@@ -4,6 +4,8 @@ use std::fs;
 
 #[path = "../src/eval.rs"]
 mod eval;
+#[path = "../src/shell_dispatcher.rs"]
+mod shell_dispatcher;
 
 use eval::{EvalHarness, EvalHarnessConfig, ScenarioStepKind};
 use tempfile::tempdir;
diff --git a/crates/tui/tests/palette_audit.rs b/crates/tui/tests/palette_audit.rs
index f8cc2805..e86c207a 100644
--- a/crates/tui/tests/palette_audit.rs
+++ b/crates/tui/tests/palette_audit.rs
@@ -1,8 +1,8 @@
 //! Palette audit tests to prevent color drift.
 //!
 //! These tests ensure that deprecated colors (like DEEPSEEK_AQUA) are not used
-//! directly in user-visible code. The palette should only use DeepSeek brand
-//! colors: blue, sky, red (plus neutral shades).
+//! directly in user-visible code. Backward-compatible DeepSeek aliases should
+//! point at the current CodeWhale semantic tokens instead of stale brand RGBs.
 
 use std::fs;
 use std::path::Path;
@@ -133,35 +133,35 @@ fn audit_no_direct_aqua_usage() {
 }
 
 #[test]
-fn verify_status_success_uses_sky() {
-    let manifest_dir = env!("CARGO_MANIFEST_DIR");
-    let palette_path = Path::new(manifest_dir).join("src/palette.rs");
-    let content = fs::read_to_string(&palette_path).expect("Failed to read palette.rs");
-
-    assert!(
-        content.contains("pub const STATUS_SUCCESS: Color = DEEPSEEK_SKY;"),
-        "STATUS_SUCCESS should use DEEPSEEK_SKY, not DEEPSEEK_AQUA"
+fn verify_status_success_uses_success_token() {
+    assert_eq!(
+        palette::STATUS_SUCCESS,
+        Color::Rgb(
+            palette::WHALE_SUCCESS_RGB.0,
+            palette::WHALE_SUCCESS_RGB.1,
+            palette::WHALE_SUCCESS_RGB.2
+        ),
+        "STATUS_SUCCESS should use the current success token"
+    );
+    assert_ne!(
+        palette::STATUS_SUCCESS,
+        palette::DEEPSEEK_AQUA,
+        "STATUS_SUCCESS should not regress to deprecated aqua"
     );
 }
 
 #[test]
-fn verify_brand_colors_defined() {
-    let manifest_dir = env!("CARGO_MANIFEST_DIR");
-    let palette_path = Path::new(manifest_dir).join("src/palette.rs");
-    let content = fs::read_to_string(&palette_path).expect("Failed to read palette.rs");
+fn verify_brand_aliases_follow_whale_tokens() {
+    assert_eq!(palette::WHALE_ACCENT_PRIMARY_RGB, (246, 196, 83));
+    assert_eq!(palette::WHALE_INFO_RGB, (106, 174, 242));
+    assert_eq!(palette::WHALE_ERROR_RGB, (255, 92, 122));
 
-    assert!(
-        content.contains("DEEPSEEK_BLUE_RGB: (u8, u8, u8) = (53, 120, 229);"),
-        "DEEPSEEK_BLUE should be #3578E5"
-    );
-    assert!(
-        content.contains("DEEPSEEK_SKY_RGB: (u8, u8, u8) = (106, 174, 242);"),
-        "DEEPSEEK_SKY should be #6AAEF2"
-    );
-    assert!(
-        content.contains("DEEPSEEK_RED_RGB: (u8, u8, u8) = (226, 80, 96);"),
-        "DEEPSEEK_RED should be #E25060"
+    assert_eq!(
+        palette::DEEPSEEK_BLUE_RGB,
+        palette::WHALE_ACCENT_PRIMARY_RGB
     );
+    assert_eq!(palette::DEEPSEEK_SKY_RGB, palette::WHALE_INFO_RGB);
+    assert_eq!(palette::DEEPSEEK_RED_RGB, palette::WHALE_ERROR_RGB);
 }
 
 #[test]
diff --git a/crates/tui/tests/reasoning_content_replayed_after_tool_call.rs b/crates/tui/tests/reasoning_content_replayed_after_tool_call.rs
new file mode 100644
index 00000000..16c0b87f
--- /dev/null
+++ b/crates/tui/tests/reasoning_content_replayed_after_tool_call.rs
@@ -0,0 +1,128 @@
+use futures_util::StreamExt;
+
+#[path = "../src/models.rs"]
+#[allow(dead_code)]
+mod models;
+
+#[path = "support/llm_client.rs"]
+mod llm_client;
+
+use crate::llm_client::LlmClient;
+use crate::llm_client::mock::{MockLlmClient, canned};
+use crate::models::{ContentBlock, Message, MessageRequest};
+
+fn user_message(text: &str) -> Message {
+    Message {
+        role: "user".to_string(),
+        content: vec![ContentBlock::Text {
+            text: text.to_string(),
+            cache_control: None,
+        }],
+    }
+}
+
+fn assistant_thinking_tool_call(
+    thinking: &str,
+    id: &str,
+    name: &str,
+    input: serde_json::Value,
+) -> Message {
+    Message {
+        role: "assistant".to_string(),
+        content: vec![
+            ContentBlock::Thinking {
+                thinking: thinking.to_string(),
+            },
+            ContentBlock::ToolUse {
+                id: id.to_string(),
+                name: name.to_string(),
+                input,
+                caller: None,
+            },
+        ],
+    }
+}
+
+fn tool_result_message(tool_use_id: &str, content: &str) -> Message {
+    Message {
+        role: "user".to_string(),
+        content: vec![ContentBlock::ToolResult {
+            tool_use_id: tool_use_id.to_string(),
+            content: content.to_string(),
+            is_error: None,
+            content_blocks: None,
+        }],
+    }
+}
+
+fn make_request(messages: Vec<Message>) -> MessageRequest {
+    MessageRequest {
+        model: "deepseek-v4-pro".to_string(),
+        messages,
+        max_tokens: 4096,
+        system: None,
+        tools: None,
+        tool_choice: None,
+        metadata: None,
+        thinking: None,
+        reasoning_effort: Some("high".to_string()),
+        stream: Some(true),
+        temperature: None,
+        top_p: None,
+    }
+}
+
+#[tokio::test]
+async fn reasoning_content_is_replayed_after_thinking_tool_call() {
+    let mock = MockLlmClient::new(vec![]);
+
+    mock.push_turn(vec![
+        canned::message_start("r1"),
+        canned::thinking_delta(0, "I should inspect /tmp before answering."),
+        canned::tool_use_block_start(1, "call_a", "list_dir"),
+        canned::tool_input_delta(1, r#"{"path":"/tmp"}"#),
+        canned::block_stop(1),
+        canned::message_delta("tool_use", None),
+        canned::message_stop(),
+    ]);
+
+    mock.push_factory(|request| {
+        let assistant = request
+            .messages
+            .iter()
+            .rev()
+            .find(|message| message.role == "assistant")
+            .expect("follow-up request must include the prior assistant tool-call turn");
+
+        assert!(
+            assistant
+                .content
+                .iter()
+                .any(|block| matches!(block, ContentBlock::Thinking { .. })),
+            "DeepSeek V4 follow-up requests must replay reasoning_content on the assistant tool-call turn"
+        );
+
+        canned::simple_text_turn("I see the /tmp entries.")
+    });
+
+    let mut first = mock
+        .create_message_stream(make_request(vec![user_message("list /tmp")]))
+        .await
+        .expect("first stream opens");
+    while first.next().await.is_some() {}
+
+    let mut second = mock
+        .create_message_stream(make_request(vec![
+            user_message("list /tmp"),
+            assistant_thinking_tool_call(
+                "I should inspect /tmp before answering.",
+                "call_a",
+                "list_dir",
+                serde_json::json!({ "path": "/tmp" }),
+            ),
+            tool_result_message("call_a", "/tmp/file1\n/tmp/file2"),
+        ]))
+        .await
+        .expect("second stream opens");
+    while second.next().await.is_some() {}
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index beeba689..ac2e9f13 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -156,7 +156,7 @@ drives turns through Chat Completions.
   - `mod.rs` - `LspManager` — lazy per-language transport pool + config
   - `client.rs` - `StdioLspTransport` — JSON-RPC over stdio with `didOpen`/`didChange`/`publishDiagnostics`
   - `diagnostics.rs` - Diagnostic types, severity, and HTML-block renderer
-  - `registry.rs` - Language detection and default server map (rust-analyzer, pyright, gopls, clangd, typescript-language-server)
+  - `registry.rs` - Language detection and default server map (rust-analyzer, pyright, gopls, clangd, typescript-language-server, jdtls, vue-language-server)
   - Wired into the engine via `core/engine/lsp_hooks.rs` — called after every successful edit
 
 ### Security
@@ -174,6 +174,7 @@ drives turns through Chat Completions.
 - **`utils.rs`** - Common utilities
 - **`logging.rs`** - Logging infrastructure
 - **`compaction.rs`** - Context compaction for long conversations
+- **`purge.rs`** - Agent-driven context purging (surgical message removal/rewriting)
 - **`pricing.rs`** - Cost estimation
 - **`prompts.rs`** - System prompt templates
 - **`project_doc.rs`** - Project documentation handling
@@ -241,7 +242,8 @@ ordinary durable tasks.
 3. Engine events are mapped to item lifecycle events (`item.started|item.delta|item.completed`)
 4. Interrupt/steer operations apply to the active turn only
 5. Compaction (auto/manual) is emitted as `context_compaction` item lifecycle
-6. Clients replay history and resume with `/v1/threads/{id}/events?since_seq=<n>`
+6. Purge (agent-driven) is emitted as `context_purge` item lifecycle
+7. Clients replay history and resume with `/v1/threads/{id}/events?since_seq=<n>`
 
 ### Durable Schema Gates
 
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 858bac7e..5ebc56f7 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -62,18 +62,22 @@ label without printing the key itself. The command only probes the active
 provider's keyring entry.
 
 For hosted, generic OpenAI-compatible, or self-hosted providers, set
-`provider = "nvidia-nim"`, `"openai"`, `"atlascloud"`, `"wanjie-ark"`, `"fireworks"`,
-`"sglang"`, `"vllm"`, or `"ollama"` or pass `codewhale --provider <name>`. The facade saves provider
-credentials to the shared user config and forwards the resolved key, base URL,
-provider, and model to the TUI process. Use
+`provider = "nvidia-nim"`, `"openai"`, `"atlascloud"`, `"wanjie-ark"`,
+`"openrouter"`, `"xiaomi-mimo"`, `"novita"`, `"fireworks"`, `"moonshot"`,
+`"sglang"`, `"vllm"`, or `"ollama"` or pass `codewhale --provider <name>`.
+For the provider-by-provider registry, including auth variables, default base
+URLs, model IDs, and capability metadata, see [PROVIDERS.md](PROVIDERS.md).
+The facade saves provider credentials to the shared user config and forwards
+the resolved key, base URL, provider, and model to the TUI process. Use
 `codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"` or
 `codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"` or
 `codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"` or
 `codewhale auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"` or
-`codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"` to
-save provider keys through the facade. The generic `openai` provider defaults
-to `https://api.openai.com/v1`, accepts `OPENAI_BASE_URL`, and passes model IDs
-through unchanged for OpenAI-compatible gateways. `atlascloud` defaults to
+`codewhale auth set --provider xiaomi-mimo --api-key "YOUR_XIAOMI_MIMO_API_KEY"` or
+`codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"`
+to save provider keys through the facade. The generic `openai` provider defaults
+to `https://api.openai.com/v1`, accepts `OPENAI_BASE_URL`, and defaults to
+`deepseek-v4-pro` for OpenAI-compatible gateways. `atlascloud` defaults to
 `https://api.atlascloud.ai/v1`, accepts `ATLASCLOUD_BASE_URL`, and uses
 `deepseek-ai/deepseek-v4-flash` as its default model. `wanjie-ark` targets
 Wanjie Ark's OpenAI-compatible endpoint at
@@ -126,6 +130,25 @@ environment override is `DEEPSEEK_HTTP_HEADERS`, using comma-separated
 and `Content-Type` are managed by the client and are not overridden by this
 setting.
 
+### Vision Model
+
+CodeWhale's chat provider and `image_analyze` tool are configured separately.
+The main chat path remains the selected text/tool provider; image analysis runs
+through `[vision_model]` when the `vision_model` feature is enabled.
+
+Xiaomi's current image-understanding docs include `mimo-v2.5` for image input.
+To use MiMo for `image_analyze`, configure the vision model explicitly:
+
+```toml
+[features]
+vision_model = true
+
+[vision_model]
+model = "mimo-v2.5"
+api_key = "YOUR_XIAOMI_MIMO_API_KEY"
+base_url = "https://api.xiaomimimo.com/v1"
+```
+
 To bootstrap MCP and skills directories at their resolved paths, run `codewhale-tui setup`.
 To only scaffold MCP, run `codewhale-tui mcp init`.
 
@@ -197,13 +220,22 @@ If a profile is selected but missing, codewhale exits with an error listing avai
 ## Environment Variables
 
 Most runtime environment variables override config values. API-key variables are
-fallbacks after saved config and keyring credentials:
+fallbacks after saved config and keyring credentials.
+
+The three user-facing slots — provider, model, base URL — expose `CODEWHALE_*`
+aliases. When both forms are set the `CODEWHALE_*` value wins; the
+`DEEPSEEK_*` form is kept for older shells:
+
+- `CODEWHALE_PROVIDER` (preferred) / `DEEPSEEK_PROVIDER` (legacy alias) —
+  `deepseek|nvidia-nim|openai|atlascloud|wanjie-ark|openrouter|xiaomi-mimo|novita|fireworks|moonshot|sglang|vllm|ollama`
+- `CODEWHALE_MODEL` (preferred) / `DEEPSEEK_MODEL` (legacy alias) — default model for the active provider
+- `CODEWHALE_BASE_URL` (preferred) / `DEEPSEEK_BASE_URL` (legacy alias) — base URL for the active provider
+
+Remaining variables:
 
 - `DEEPSEEK_API_KEY`
-- `DEEPSEEK_BASE_URL`
 - `DEEPSEEK_HTTP_HEADERS` (custom model request headers, comma-separated `name=value` pairs)
-- `DEEPSEEK_PROVIDER` (`codewhale|nvidia-nim|openai|atlascloud|wanjie-ark|openrouter|novita|fireworks|sglang|vllm|ollama`)
-- `DEEPSEEK_MODEL` or `DEEPSEEK_DEFAULT_TEXT_MODEL`
+- `DEEPSEEK_DEFAULT_TEXT_MODEL` (extra legacy alias of `DEEPSEEK_MODEL`)
 - `DEEPSEEK_STREAM_IDLE_TIMEOUT_SECS` (stream idle timeout in seconds; default `300`, clamped to `1..=3600`)
 - `DEEPSEEK_STREAM_OPEN_TIMEOUT_SECS` (connection setup + response-header wait in seconds; default `45`, clamped to `5..=300`; distinct from the per-chunk idle timeout)
 - `NVIDIA_API_KEY` or `NVIDIA_NIM_API_KEY` (preferred when provider is `nvidia-nim`; falls back to `DEEPSEEK_API_KEY`)
@@ -220,10 +252,16 @@ fallbacks after saved config and keyring credentials:
 - `WANJIE_ARK_MODEL`, `WANJIE_MODEL`, or `WANJIE_MAAS_MODEL`
 - `OPENROUTER_API_KEY`
 - `OPENROUTER_BASE_URL`
+- `XIAOMI_MIMO_API_KEY` or `MIMO_API_KEY`
+- `XIAOMI_MIMO_BASE_URL` or `MIMO_BASE_URL`
+- `XIAOMI_MIMO_MODEL` or `MIMO_MODEL`
 - `NOVITA_API_KEY`
 - `NOVITA_BASE_URL`
 - `FIREWORKS_API_KEY`
 - `FIREWORKS_BASE_URL`
+- `MOONSHOT_API_KEY` or `KIMI_API_KEY`
+- `MOONSHOT_BASE_URL` or `KIMI_BASE_URL`
+- `MOONSHOT_MODEL`, `KIMI_MODEL_NAME`, or `KIMI_MODEL`
 - `SGLANG_BASE_URL`
 - `SGLANG_MODEL`
 - `SGLANG_API_KEY` (optional; many localhost SGLang servers do not require auth)
@@ -250,8 +288,6 @@ fallbacks after saved config and keyring credentials:
 - `DEEPSEEK_FORCE_HTTP1` (`1|true|yes|on` pins the HTTP client to HTTP/1.1, disabling HTTP/2; useful on Windows or behind proxies that mishandle long-lived H2 streams)
 - `DEEPSEEK_HOME` (override the base data directory; defaults to `~/.deepseek`)
 - `DEEPSEEK_AUTOMATIONS_DIR` (override the automations storage directory; defaults to `~/.deepseek/automations`)
-- `DEEPSEEK_VOICE_INPUT_COMMAND` (command used by command-palette Voice input; stdout must be the final transcript)
-- `DEEPSEEK_VOICE_INPUT_TIMEOUT_SECS` (voice input command timeout, clamped to `1..=600`, default `60`)
 - `DEEPSEEK_CAPACITY_ENABLED`
 - `DEEPSEEK_CAPACITY_LOW_RISK_MAX`
 - `DEEPSEEK_CAPACITY_MEDIUM_RISK_MAX`
@@ -372,59 +408,11 @@ Common settings keys:
 - `max_history` (number of submitted input history entries; cleared drafts are
   also kept locally for composer history search)
 - `default_model` (model name override)
-- `voice_input_command` (command run by command-palette Voice input; stdout is
-  inserted into the composer as transcript text)
-- `voice_input_timeout_secs` (1-600 seconds, default 60)
 
 Only `agent`, `plan`, and `yolo` are visible modes in the UI. Switch between
 them with `/mode`. For compatibility, older settings files with
 `default_mode = "normal"` still load as `agent`.
 
-### Voice Input
-
-Voice input is intentionally a command bridge instead of a built-in speech SDK.
-The configured command owns microphone permission, recording, and
-speech-to-text. CodeWhale runs it in the background with a listening status,
-reads stdout, trims surrounding whitespace, and inserts the transcript into the
-composer at the cursor.
-Open it from the command palette with `Ctrl+K`, then search `Voice input`.
-
-```toml
-voice_input_command = "codewhale-voice"
-voice_input_timeout_secs = 60
-```
-
-The command must:
-
-- exit `0` on success
-- write only the final transcript to stdout
-- write diagnostics to stderr
-- avoid putting API keys directly in the command string; read secrets from the
-  environment or OS key store instead
-
-Platform helper patterns:
-
-- macOS: use a small helper around a local STT tool or Apple's Speech framework,
-  then set `voice_input_command = "codewhale-voice"`. Apple's framework supports
-  live and recorded speech recognition, but microphone and speech permissions
-  belong in the helper, not the terminal UI.
-- Windows: use a PowerShell, .NET, or WinRT helper around
-  `Windows.Media.SpeechRecognition`. Prefer forward slashes in configured paths,
-  for example
-  `voice_input_command = "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:/Users/me/bin/codewhale-voice.ps1"`.
-- HarmonyOS/Huawei devices: use a native, ArkTS/Java, or device-bridge helper
-  that calls the platform/Huawei ASR capability and prints UTF-8 transcript text.
-  This keeps the Rust TUI portable while letting the HarmonyOS side own device
-  permissions and SDK packaging.
-
-Useful native references for helper authors:
-
-- Apple Speech framework: <https://developer.apple.com/documentation/speech/>
-- Windows speech recognition APIs:
-  <https://learn.microsoft.com/en-us/windows/apps/develop/input/speech-recognition>
-- Huawei ML Kit ASR codelab:
-  <https://developer.huawei.com/consumer/en/codelab/AirTouch/>
-
 Localization scope is tracked in [LOCALIZATION.md](LOCALIZATION.md). The v0.7.6
 core pack covers high-visibility TUI chrome only; provider/tool schemas,
 personality prompts, and full documentation remain English unless explicitly
@@ -476,10 +464,10 @@ If you are upgrading from older releases:
 
 ### Core keys (used by the TUI/engine)
 
-- `provider` (string, optional): `codewhale` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `novita`, `fireworks`, `sglang`, `vllm`, or `ollama`. Legacy `deepseek-cn` configs are still accepted as an alias for `codewhale`; DeepSeek uses the same official host [`https://api.deepseek.com`](https://api-docs.deepseek.com/) worldwide. `nvidia-nim` targets NVIDIA's NIM-hosted DeepSeek endpoints through `https://integrate.api.nvidia.com/v1`; `openai` targets a generic OpenAI-compatible endpoint, defaulting to `https://api.openai.com/v1`; `atlascloud` targets AtlasCloud's OpenAI-compatible endpoint at `https://api.atlascloud.ai/v1`; `wanjie-ark` targets Wanjie Ark's OpenAI-compatible endpoint at `https://maas-openapi.wanjiedata.com/api/v1`; `fireworks` targets `https://api.fireworks.ai/inference/v1`; `sglang` targets a self-hosted OpenAI-compatible endpoint, defaulting to `http://localhost:30000/v1`; `vllm` targets a self-hosted vLLM OpenAI-compatible endpoint, defaulting to `http://localhost:8000/v1`; `ollama` targets Ollama's OpenAI-compatible endpoint, defaulting to `http://localhost:11434/v1`.
+- `provider` (string, optional): `deepseek` (default), `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `openrouter`, `xiaomi-mimo`, `novita`, `fireworks`, `moonshot`, `sglang`, `vllm`, or `ollama`. Legacy `deepseek-cn` configs are still accepted as an alias for `deepseek`; DeepSeek uses the same official host [`https://api.deepseek.com`](https://api-docs.deepseek.com/) worldwide. `nvidia-nim` targets NVIDIA's NIM-hosted DeepSeek endpoints through `https://integrate.api.nvidia.com/v1`; `openai` targets a generic OpenAI-compatible endpoint, defaulting to `https://api.openai.com/v1`; `atlascloud` targets AtlasCloud's OpenAI-compatible endpoint at `https://api.atlascloud.ai/v1`; `wanjie-ark` targets Wanjie Ark's OpenAI-compatible endpoint at `https://maas-openapi.wanjiedata.com/api/v1`; `openrouter` targets `https://openrouter.ai/api/v1`; `xiaomi-mimo` targets Xiaomi MiMo's OpenAI-compatible endpoint at `https://api.xiaomimimo.com/v1`; `novita` targets `https://api.novita.ai/v1`; `fireworks` targets `https://api.fireworks.ai/inference/v1`; `moonshot` targets Moonshot/Kimi, defaulting to `https://api.moonshot.ai/v1`; `sglang` targets a self-hosted OpenAI-compatible endpoint, defaulting to `http://localhost:30000/v1`; `vllm` targets a self-hosted vLLM OpenAI-compatible endpoint, defaulting to `http://localhost:8000/v1`; `ollama` targets Ollama's OpenAI-compatible endpoint, defaulting to `http://localhost:11434/v1`.
 - `api_key` (string, required for hosted providers): must be non-empty for DeepSeek/hosted providers (or set the provider API key env var). Self-hosted SGLang, vLLM, and Ollama can omit it.
-- `base_url` (string, optional): defaults to `https://api.deepseek.com/beta` for DeepSeek's OpenAI-compatible Chat Completions API, including legacy `provider = "deepseek-cn"` configs, `https://api.openai.com/v1` for `provider = "openai"`, `https://api.atlascloud.ai/v1` for `provider = "atlascloud"`, `https://maas-openapi.wanjiedata.com/api/v1` for `provider = "wanjie-ark"`, or the provider-specific endpoint for hosted/self-hosted providers. Set `https://api.deepseek.com` or `https://api.deepseek.com/v1` explicitly to opt out of DeepSeek beta features.
-- `default_text_model` (string, optional): defaults to `deepseek-v4-pro` for DeepSeek, `deepseek-ai/deepseek-v4-pro` for NVIDIA NIM, `gpt-4.1` for generic OpenAI-compatible endpoints, `deepseek-ai/deepseek-v4-flash` for AtlasCloud, `deepseek-reasoner` for Wanjie Ark, `accounts/fireworks/models/deepseek-v4-pro` for Fireworks, `deepseek-ai/DeepSeek-V4-Pro` for SGLang/vLLM, and `codewhale-coder:1.3b` for Ollama. Current public DeepSeek IDs are `deepseek-v4-pro` and `deepseek-v4-flash`, both with 1M context windows, 384K max output, and thinking mode enabled by default. Legacy `deepseek-chat` and `deepseek-reasoner` remain compatibility aliases for `deepseek-v4-flash` until July 24, 2026. Provider-specific mappings translate `deepseek-v4-pro` / `deepseek-v4-flash` to each provider's model ID where supported. Generic `openai`, `atlascloud`, `wanjie-ark`, and Ollama model IDs are passed through unchanged. OpenRouter provider configs with a custom `base_url` also preserve explicit model values, which lets OpenAI-compatible gateways accept bare model IDs. Use `/models` or `codewhale models` to discover live IDs from your configured endpoint. `DEEPSEEK_MODEL` overrides this for a single process.
+- `base_url` (string, optional): defaults to `https://api.deepseek.com/beta` for DeepSeek's OpenAI-compatible Chat Completions API, including legacy `provider = "deepseek-cn"` configs. Other defaults are `https://integrate.api.nvidia.com/v1` for `nvidia-nim`, `https://api.openai.com/v1` for `openai`, `https://api.atlascloud.ai/v1` for `atlascloud`, `https://maas-openapi.wanjiedata.com/api/v1` for `wanjie-ark`, `https://openrouter.ai/api/v1` for `openrouter`, `https://api.xiaomimimo.com/v1` for `xiaomi-mimo`, `https://api.novita.ai/v1` for `novita`, `https://api.fireworks.ai/inference/v1` for `fireworks`, `https://api.moonshot.ai/v1` for `moonshot`, `http://localhost:30000/v1` for `sglang`, `http://localhost:8000/v1` for `vllm`, and `http://localhost:11434/v1` for `ollama`. Set `https://api.deepseek.com` or `https://api.deepseek.com/v1` explicitly to opt out of DeepSeek beta features.
+- `default_text_model` (string, optional): defaults to `deepseek-v4-pro` for DeepSeek and generic OpenAI-compatible endpoints, `deepseek-ai/deepseek-v4-pro` for NVIDIA NIM, `deepseek-ai/deepseek-v4-flash` for AtlasCloud, `deepseek-reasoner` for Wanjie Ark, `deepseek/deepseek-v4-pro` for OpenRouter and Novita, `mimo-v2.5-pro` for Xiaomi MiMo, `accounts/fireworks/models/deepseek-v4-pro` for Fireworks, `kimi-k2.6` for Moonshot, `deepseek-ai/DeepSeek-V4-Pro` for SGLang/vLLM, and `deepseek-coder:1.3b` for Ollama. Current public DeepSeek IDs are `deepseek-v4-pro` and `deepseek-v4-flash`, both with 1M context windows, 384K max output, and thinking mode enabled by default. Legacy `deepseek-chat` and `deepseek-reasoner` remain compatibility aliases for `deepseek-v4-flash` until July 24, 2026. Provider-specific mappings translate `deepseek-v4-pro` / `deepseek-v4-flash` to each provider's model ID where supported. Generic `openai`, `atlascloud`, `wanjie-ark`, `xiaomi-mimo`, and Ollama model IDs are passed through unchanged. OpenRouter provider configs with a custom `base_url` also preserve explicit model values, which lets OpenAI-compatible gateways accept bare model IDs. Use `/models` or `codewhale models` to discover live IDs from your configured endpoint. `CODEWHALE_MODEL` overrides this for a single process; `DEEPSEEK_MODEL` is the legacy alias.
 - `reasoning_effort` (string, optional): `off`, `low`, `medium`, `high`, or `max`; defaults to the configured UI tier. DeepSeek Platform receives top-level `thinking` / `reasoning_effort` fields. NVIDIA NIM receives equivalent settings through `chat_template_kwargs`.
 - `allow_shell` (bool, optional): defaults to `true` (sandboxed).
 - `approval_policy` (string, optional): `on-request`, `untrusted`, or `never`. Runtime `approval_mode` editing in `/config` also accepts `on-request` and `untrusted` aliases.
@@ -581,7 +569,7 @@ If you are upgrading from older releases:
   `false`. When `true`, the notification body includes the elapsed
   duration and the turn's cost in the configured display currency.
 - `tui.alternate_screen` (string, optional): `auto`, `always`, or `never`. This is retained for config compatibility, but interactive sessions now always use the TUI-owned alternate screen so host terminal scrollback cannot hijack the viewport.
-- `tui.mouse_capture` (bool, optional, default `true` on non-Windows terminals and on Windows Terminal/ConEmu/Cmder when the alternate screen is active; `false` on legacy Windows console and inside JetBrains JediTerm — PyCharm/IDEA/CLion/etc. — where mouse-event escapes leak into the input stream as garbled text, see #878 / #898): enable internal mouse scrolling, transcript selection, right-click context actions, and transcript scrollbar dragging. TUI-owned drag selection copies only transcript text and keeps selection scoped to the transcript pane. Set this to `false` or run with `--no-mouse-capture` for raw terminal selection; set it to `true` or run with `--mouse-capture` to opt in anywhere it's defaulted off. On raw terminal selection, especially on legacy Windows console or when mouse capture is disabled, selection may cross the right sidebar because the terminal, not the TUI, owns the selection.
+- `tui.mouse_capture` (bool, optional, default `true` on non-Windows terminals and on Windows Terminal/ConEmu/Cmder when the alternate screen is active; `false` on legacy Windows console and inside JetBrains JediTerm — PyCharm/IDEA/CLion/etc. — where mouse-event escapes leak into the input stream as garbled text, see #878 / #898): enable internal mouse scrolling, transcript selection, right-click context actions, and transcript scrollbar dragging. TUI-owned drag selection copies only transcript text, removes visual wrap-column line breaks from paragraphs, and keeps selection scoped to the transcript pane. Set this to `false` or run with `--no-mouse-capture` for raw terminal selection; set it to `true` or run with `--mouse-capture` to opt in anywhere it's defaulted off. On raw terminal selection, especially on legacy Windows console or when mouse capture is disabled, selection may cross the right sidebar and include visual wraps because the terminal, not the TUI, owns the selection.
 - `tui.terminal_probe_timeout_ms` (int, optional, default `500`): startup terminal-mode probe timeout in milliseconds. Values are clamped to `100..=5000`; timeout emits a warning and aborts startup instead of hanging indefinitely.
 - `tui.osc8_links` (bool, optional, default `true`): emit OSC 8 escape sequences around URLs in transcript output so terminals that support them (iTerm2, Terminal.app 13+, Ghostty, Kitty, WezTerm, Alacritty, recent gnome-terminal/konsole) render them as Cmd+click hyperlinks. Terminals without OSC 8 support render the plain URL and ignore the escape. Set `false` for terminals that misrender the sequence; selection/clipboard output always strips the escapes.
 - `hooks` (optional): lifecycle hooks configuration (see `config.example.toml`).
@@ -659,6 +647,17 @@ These keys are accepted by the config loader but not currently used by the inter
 
 - `tools_file`
 
+## Tool Catalog
+
+CodeWhale loads a small core native tool catalog by default and leaves less
+common native tools discoverable through ToolSearch. To keep specific native
+tools loaded on every request, add them to `[tools].always_load`:
+
+```toml
+[tools]
+always_load = ["git_show", "notify"]
+```
+
 ## Feature Flags
 
 Feature flags live under the `[features]` table and are merged across profiles.
@@ -684,14 +683,24 @@ Use `codewhale-tui features list` to inspect known flags and their effective sta
 
 ## Web Search Provider
 
-`web_search` uses Bing by default and does not require an API key. DuckDuckGo
-remains selectable for users who explicitly want it, and Tavily or Bocha can be
-selected when an API-backed provider is preferred.
+`web_search` uses DuckDuckGo by default and does not require an API key. The
+DuckDuckGo path keeps a Bing fallback when DDG returns a bot challenge or no
+parseable results. Bing remains selectable for users who explicitly want it,
+and Tavily, Bocha, Metaso, or Baidu can be selected when an API-backed provider
+is preferred.
+
+**Metaso** ([metaso.cn](https://metaso.cn)) has a 100 searches/day free quota;
+set `METASO_API_KEY` or `[search] api_key` for a higher quota.
+
+**Baidu** uses Baidu AI Search at
+`https://qianfan.baidubce.com/v2/ai_search/web_search`. Set
+`BAIDU_SEARCH_API_KEY` or `[search] api_key`. This is a search-tool backend
+only; it does not add a Baidu model provider.
 
 ```toml
 [search]
-provider = "bing" # bing | duckduckgo | tavily | bocha
-# api_key = "tvly-YOUR_KEY" # required for tavily and bocha
+provider = "baidu" # duckduckgo | bing | tavily | bocha | metaso | baidu
+# api_key = "YOUR_KEY" # required for tavily, bocha, and baidu; optional for metaso
 ```
 
 ## Local Media Attachments
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 732c4705..fa1c075f 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -36,6 +36,164 @@ docker run --rm -it \
 Replace `vX.Y.Z` with a tag from
 [GitHub Releases](https://github.com/Hmbown/CodeWhale/releases).
 
+## Default image contract
+
+`ghcr.io/hmbown/codewhale:latest` and the semver tags are conservative runtime
+images:
+
+- the container runs as the non-root `codewhale` user with UID/GID `1000:1000`
+- the image does not grant passwordless `sudo`
+- the image is meant to run CodeWhale against mounted workspaces, not to mutate
+  the base operating system at runtime
+- user state belongs in a volume mounted at `/home/codewhale/.deepseek`
+
+That default is intentional. Keep using it for the smallest trust boundary. If a
+project needs `apt-get`, compiler toolchains, Node/Python package managers,
+custom CA certificates, or other host-like setup inside Docker, build an
+explicit toolbox image instead of changing the default image contract.
+
+## Opt-in toolbox/custom image
+
+The repository includes an example
+[`docs/examples/Dockerfile.toolbox`](examples/Dockerfile.toolbox) that extends
+the official image with passwordless `sudo` and common development packages.
+Build it with a pinned CodeWhale tag when you want repeatable project
+environments:
+
+```bash
+docker build -f docs/examples/Dockerfile.toolbox \
+  --build-arg CODEWHALE_IMAGE=ghcr.io/hmbown/codewhale:vX.Y.Z \
+  --build-arg TOOLBOX_PACKAGES="git openssh-client curl build-essential pkg-config python3 python3-pip nodejs npm" \
+  -t codewhale-toolbox:my-project .
+```
+
+Use `latest` only for throwaway testing. For shared projects, keep the
+`CODEWHALE_IMAGE` value pinned and review package additions like any other
+development-environment change.
+
+Run the toolbox image with the same workspace and state mounts:
+
+```bash
+docker volume create codewhale-my-project-home
+
+docker run --rm -it \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  -v codewhale-my-project-home:/home/codewhale/.deepseek \
+  -v "$PWD:/workspace" \
+  -w /workspace \
+  codewhale-toolbox:my-project
+```
+
+Inside this opt-in image, CodeWhale can use commands such as
+`sudo apt-get update` and `sudo apt-get install -y <package>`. For repeatable
+containers, prefer baking those packages into the toolbox Dockerfile instead of
+letting a long-lived container drift.
+
+Do not bake API keys, SSH private keys, or other secrets into custom images.
+Pass API keys at runtime and mount any SSH material deliberately, preferably
+read-only and only for projects that need it.
+
+### Compose toolbox template
+
+If you prefer a repeatable `docker compose` entry point, use
+[`docs/examples/compose.toolbox.yml`](examples/compose.toolbox.yml). It builds
+the toolbox image from [`docs/examples/Dockerfile.toolbox`](examples/Dockerfile.toolbox)
+and keeps the project state volume explicit:
+
+```bash
+CODEWHALE_IMAGE=ghcr.io/hmbown/codewhale:vX.Y.Z \
+CODEWHALE_TOOLBOX_IMAGE=codewhale-toolbox:my-project \
+CODEWHALE_HOME_VOLUME=codewhale-my-project-home \
+CODEWHALE_WORKSPACE="$PWD" \
+docker compose -f docs/examples/compose.toolbox.yml run --rm codewhale
+```
+
+Use a different `CODEWHALE_TOOLBOX_IMAGE` and `CODEWHALE_HOME_VOLUME` for each
+project that needs an independent toolchain or independent `.deepseek` state.
+The Compose file also shows opt-in, read-only mounts for SSH material and local
+CA certificates; keep those commented out unless the project needs them.
+
+## Multiple independent projects
+
+Use one named state volume per project so sessions, config, skills, memory, and
+the offline queue do not bleed across workspaces:
+
+```bash
+project="$(basename "$PWD")"
+image="codewhale-toolbox:${project}"
+docker volume create "codewhale-${project}-home"
+
+docker run --rm -it \
+  --name "codewhale-${project}" \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  -v "codewhale-${project}-home:/home/codewhale/.deepseek" \
+  -v "$PWD:/workspace" \
+  -w /workspace \
+  "$image"
+```
+
+For projects with different toolchains, build different toolbox tags, for
+example `codewhale-toolbox:frontend` and `codewhale-toolbox:backend`. The
+separate launcher idea discussed in issue #2217 can build on this contract, but
+it is intentionally outside the core Docker image.
+
+## Project bootstrap scripts
+
+CodeWhale does not automatically execute `.deepseek/setup.sh` or
+`.codewhale/setup.sh`. If you keep one of those files as a local project
+recipe, run it explicitly. For shared team setup, prefer a committed project
+script or the toolbox Dockerfile so the environment can be reviewed and
+rebuilt.
+
+For example, to run a committed bootstrap script before starting CodeWhale:
+
+```bash
+docker run --rm -it \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  -v codewhale-my-project-home:/home/codewhale/.deepseek \
+  -v "$PWD:/workspace" \
+  -w /workspace \
+  --entrypoint bash \
+  codewhale-toolbox:my-project \
+  -lc './scripts/bootstrap-dev.sh && exec codewhale'
+```
+
+Use the toolbox image for bootstrap scripts that need `sudo`. The default image
+will not elevate privileges.
+
+## Custom CA certificates and proxies
+
+For corporate proxies, dev-sidecar, or self-signed internal services, prefer
+baking trusted CA certificates into a custom toolbox image:
+
+```dockerfile
+USER root
+COPY docker/certs/*.crt /usr/local/share/ca-certificates/
+RUN update-ca-certificates
+USER codewhale
+```
+
+All files copied into `/usr/local/share/ca-certificates/` must use the `.crt`
+extension. Keep private CA material out of public images.
+
+For a local-only run, mount certificates read-only and update the trust store at
+container start:
+
+```bash
+docker run --rm -it \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  -v codewhale-my-project-home:/home/codewhale/.deepseek \
+  -v "$PWD:/workspace" \
+  -v "$PWD/docker/certs:/usr/local/share/ca-certificates/local:ro" \
+  -w /workspace \
+  --entrypoint bash \
+  codewhale-toolbox:my-project \
+  -lc 'sudo update-ca-certificates && exec codewhale'
+```
+
+This CA workflow requires the opt-in toolbox image because the default image
+does not include passwordless `sudo`.
+
 ## Local build
 
 Build the image locally from a checkout:
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
new file mode 100644
index 00000000..60362570
--- /dev/null
+++ b/docs/GUIDE.md
@@ -0,0 +1,501 @@
+# CodeWhale User Guide
+
+This guide is for your first hour with CodeWhale. It explains the main
+workflow, the important safety controls, and where to go next when you need a
+complete reference.
+
+CodeWhale has deeper reference documents for installation, configuration,
+providers, modes, keybindings, tools, and operations. Use this page as a guided
+walkthrough, then follow the "Next" links when you need every option.
+
+## 1. Welcome to CodeWhale
+
+CodeWhale is a terminal coding agent. You run it from a workspace, give it a
+task, and it can use structured tools to inspect files, run commands, edit
+code, and report back with evidence.
+
+The important difference from a normal chat model is that CodeWhale is built
+around a harness:
+
+- It keeps the active workspace and session visible.
+- It routes each turn through explicit modes and approval rules.
+- It shows tool calls in the transcript instead of hiding the work.
+- It can preserve sessions, fork conversations, and continue later.
+- It can run sub-agents for focused background work.
+
+You can use CodeWhale for small questions:
+
+```text
+Explain the authentication flow in this repository.
+```
+
+You can also use it for multi-step work:
+
+```text
+Find the failing validation path, propose a fix, and wait for my approval
+before editing files.
+```
+
+For a new repository, start conservatively. Ask CodeWhale to explore and plan
+before asking it to change files. That gives you a reviewable path and makes it
+easier to catch wrong assumptions early.
+
+Next: [ARCHITECTURE.md](ARCHITECTURE.md) explains the internal harness and
+runtime model.
+
+## 2. First Launch
+
+Install CodeWhale with the path that fits your machine. Each supported install
+path provides both the `codewhale` dispatcher and the `codewhale-tui` runtime.
+
+```bash
+# npm
+npm install -g codewhale
+
+# Cargo
+cargo install codewhale-cli --locked
+cargo install codewhale-tui --locked
+
+# Homebrew
+# The tap/formula name is legacy; it installs codewhale and codewhale-tui.
+brew tap Hmbown/deepseek-tui
+brew install deepseek-tui
+```
+
+Docker is also available when you want an isolated runtime:
+
+```bash
+docker volume create codewhale-home
+docker run --rm -it \
+  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
+  -v codewhale-home:/home/codewhale/.codewhale \
+  -v "$PWD:/workspace" \
+  -w /workspace \
+  ghcr.io/hmbown/codewhale:latest
+```
+
+Launch CodeWhale from the repository or directory you want it to work in:
+
+```bash
+codewhale
+```
+
+On first launch, CodeWhale needs an API key for the active provider. DeepSeek is
+the default provider. The most direct setup path is:
+
+```bash
+codewhale auth set --provider deepseek
+```
+
+You can also provide a key through the environment:
+
+```bash
+export DEEPSEEK_API_KEY="your-key"
+codewhale
+```
+
+New CodeWhale config is stored under `~/.codewhale/config.toml`. Legacy
+`~/.deepseek/config.toml` files are still supported for users migrating from
+the old name.
+
+After setup, run a doctor check:
+
+```bash
+codewhale doctor
+```
+
+Use the JSON form when you need a machine-readable report for an issue:
+
+```bash
+codewhale doctor --json
+```
+
+If the doctor command reports that a rejected key came from the environment,
+remove or replace that environment variable before testing saved config again.
+
+Next: [INSTALL.md](INSTALL.md) covers platform-specific install paths,
+[CONFIGURATION.md](CONFIGURATION.md) covers config resolution, and
+[PROVIDERS.md](PROVIDERS.md) covers provider IDs and credentials.
+
+## 3. Your First Task
+
+Start with a read-only task in a real workspace:
+
+```text
+Map the repository structure and tell me where the CLI entrypoint lives.
+```
+
+Then ask for a focused plan:
+
+```text
+I want to add a small validation for empty config values. Inspect the relevant
+code and propose the smallest safe change before editing anything.
+```
+
+When you are ready for edits, be specific about the acceptance criteria:
+
+```text
+Implement the validation you proposed. Keep the change scoped to config
+parsing, add or update the narrowest test, and run the relevant check.
+```
+
+Good first prompts include four details:
+
+- The outcome you want.
+- The files, feature, or behavior you care about.
+- What is out of scope.
+- What verification should count as done.
+
+For example:
+
+```text
+Fix the broken provider error message in the config loader. Do not change the
+provider registry. Add a regression test and run only the config crate tests.
+```
+
+If you are not sure where the bug is, say that:
+
+```text
+Investigate why `codewhale doctor` reports the wrong provider. Do not edit
+files yet. Return the likely cause, evidence, and a proposed patch plan.
+```
+
+CodeWhale works best when you let investigation and implementation happen in
+separate steps for unfamiliar code. For small, well-understood changes, a
+single implementation request is fine.
+
+Next: [MODES.md](MODES.md) explains when to use Plan, Agent, and YOLO.
+
+## 4. Understanding the Interface
+
+The interactive TUI has a few stable regions:
+
+- Header: current session, active model, mode, and high-level status.
+- Transcript: the conversation, tool calls, command output summaries, and
+  model responses.
+- Composer: where you type prompts, slash commands, and file mentions.
+- Sidebar: contextual panels for work state, tasks, agents, or related
+  session information.
+- Status and footer areas: live activity, queued follow-ups, and short command
+  hints.
+
+The transcript is the audit trail. When CodeWhale reads files, runs commands,
+or edits code, the action appears there. If a command fails, use the visible
+failure output as part of your next instruction instead of starting over.
+
+The composer accepts normal prompts and slash commands. Type `/` to discover
+available commands. Use file mentions when you want the model to focus on a
+specific file or directory instead of searching broadly.
+
+The sidebar is useful when a turn spans multiple steps. It can keep goals,
+agent state, and contextual information visible while the transcript continues
+to grow.
+
+Keyboard shortcuts vary by context, terminal, and platform. This guide avoids
+duplicating the full shortcut catalog so it does not drift from the TUI.
+
+Next: [KEYBINDINGS.md](KEYBINDINGS.md) is the complete shortcut reference.
+
+## 5. Modes
+
+CodeWhale has three visible TUI modes:
+
+| Mode | Use it for | Default posture |
+| --- | --- | --- |
+| Plan | Exploration, design, and review before changes | Read-only investigation |
+| Agent | Normal multi-step coding work | Tool use with approval gates |
+| YOLO | Trusted repos where you want automatic execution | Auto-approval and trust |
+
+Switch modes from the TUI with the mode picker:
+
+```text
+/mode
+```
+
+Or switch directly:
+
+```text
+/mode plan
+/mode agent
+/mode yolo
+```
+
+Plan mode is the safest place to start in an unfamiliar repository. It is for
+inspection and decision-making, not file edits.
+
+Agent mode is the default for most contribution work. It lets CodeWhale read,
+run checks, and edit files while keeping risky actions behind approval gates.
+
+YOLO mode is for trusted workspaces where you intentionally want the model to
+act without stopping for approvals. Do not use it in a repository you do not
+trust.
+
+Modes are separate from model routing. `Tab` cycles visible modes when the
+composer is idle, while `/model auto` controls model and thinking selection for
+turns.
+
+You can also change approval behavior from `/config` by editing the approval
+mode. Use this only when you understand how it changes tool execution.
+
+Next: [MODES.md](MODES.md) has the full mode, approval, and trust-mode
+reference.
+
+## 6. Slash Commands
+
+Slash commands are typed into the composer. They are useful when you want to
+change CodeWhale state directly instead of asking the model in natural
+language.
+
+Common commands for first-time users:
+
+| Command | Use |
+| --- | --- |
+| `/mode` | Open the mode picker or switch with `/mode agent` |
+| `/model` | Select a model or use `/model auto` |
+| `/models` | Fetch or list models from the active endpoint |
+| `/provider` | Pick the active API provider |
+| `/config` | Edit runtime and provider settings |
+| `/settings` | Inspect persistent UI preferences |
+| `/compact` | Summarize long context to recover token budget |
+| `/review` | Ask for a structured review workflow |
+| `/memory` | Inspect or manage memory when enabled |
+| `/mcp` | Configure or inspect MCP server integration |
+
+Use `/provider` when you want to switch away from the default DeepSeek route.
+Provider IDs, environment variables, model defaults, and capability notes are
+kept in the provider registry document.
+
+Use `/model auto` when you want CodeWhale to choose the model and thinking
+level per turn. Use a fixed model when you need repeatable benchmarking or a
+strict cost profile.
+
+Use `/compact` when a session gets long and the model starts carrying too much
+history. Compaction trades raw transcript detail for a concise working summary.
+
+This guide intentionally does not list every command. The command surface
+changes more often than the onboarding flow, and the TUI command palette is the
+source of truth while you are inside a session.
+
+Next: [CONFIGURATION.md](CONFIGURATION.md) covers runtime settings and
+[MCP.md](MCP.md) covers Model Context Protocol integration.
+
+## 7. Working with Tools
+
+CodeWhale tools are structured actions. Instead of only producing prose, the
+model can call tools to inspect and change the workspace.
+
+Examples of tool-backed work include:
+
+- Reading a file before explaining it.
+- Searching for call sites before proposing a refactor.
+- Running a focused test command.
+- Applying a small patch.
+- Opening a sub-agent for parallel investigation.
+
+Tool use is governed by mode, approvals, and sandbox policy. The exact behavior
+depends on the current mode and config, but the basic rule is simple: start in
+Plan for read-only exploration, use Agent for normal changes, and reserve YOLO
+for trusted automation.
+
+The workspace boundary matters. CodeWhale is expected to work in the directory
+you launched it from or the workspace you configured. Be explicit when a task
+should stay inside a repo:
+
+```text
+Only inspect and edit files under this repository. Do not touch parent
+directories or global config.
+```
+
+When a command needs network, writes outside the workspace, or a risky shell
+operation, expect an approval prompt unless you have configured more permissive
+behavior.
+
+Good tool instructions are concrete:
+
+```text
+Run the narrowest test that covers this parser change. If it fails, report the
+failure and stop before broadening the test scope.
+```
+
+Avoid asking for broad cleanup during a focused fix. Smaller tool scopes make
+the transcript easier to review and the final diff easier to merge.
+
+Next: [TOOL_SURFACE.md](TOOL_SURFACE.md) lists the tool surface and
+[SANDBOX.md](SANDBOX.md) explains sandbox behavior.
+
+## 8. Sub-agents and Parallel Work
+
+Sub-agents are background child agents. The parent session gives a child a
+focused task, receives an agent id, and can continue working while the child
+runs.
+
+The main orchestration tools are:
+
+- `agent_open`: start a child with a task and role.
+- `agent_eval`: wait for and collect the child result.
+- `agent_close`: cancel a running child.
+
+You normally do not need to call these tools directly. Ask for parallel work in
+plain language:
+
+```text
+Open one read-only explorer for the config crate and another for the TUI
+provider picker. Have both return file references and risks before we plan the
+fix.
+```
+
+Useful roles include:
+
+| Role | Good for |
+| --- | --- |
+| `general` | Multi-step tasks; the default when no role is specified |
+| `explore` | Read-only code mapping |
+| `plan` | Design and migration planning |
+| `review` | Bug-focused review of an existing change |
+| `implementer` | A tightly specified edit |
+| `verifier` | Running checks and reporting pass/fail evidence |
+
+Sub-agents are most useful when work can be separated cleanly. Do not use them
+for tiny edits, and do not ask multiple agents to write the same files at the
+same time.
+
+Next: [SUBAGENTS.md](SUBAGENTS.md) covers roles, lifecycle, concurrency, and
+output contracts.
+
+## 9. Skills
+
+Skills are reusable instruction packs. A skill is usually a `SKILL.md` file
+that teaches CodeWhale how to perform a recurring workflow, use a tool family,
+or follow a project convention.
+
+Use skills when a task has a repeatable process:
+
+- Reviewing a specific kind of PR.
+- Working with a document or spreadsheet format.
+- Following a team release checklist.
+- Using a project-specific memory or wiki workflow.
+
+Inside the TUI, `/skill` activates a skill when one is available, and `/skills`
+lists installed skills. The command palette can also surface skill entries
+alongside normal slash commands.
+
+Good skills are narrow. They should tell the model what workflow to follow,
+what evidence to collect, and what to avoid. They should not hide credentials
+or replace normal repository documentation.
+
+If a repository has its own instructions, treat them as part of the active
+work. Read the local guidance before editing, and keep any contribution within
+the repository's conventions.
+
+Next: see the "Publishing Your Own Skill" section in [README.md](../README.md)
+and configuration details in [CONFIGURATION.md](CONFIGURATION.md).
+
+## 10. Getting Help
+
+Start with doctor output:
+
+```bash
+codewhale doctor
+```
+
+Use JSON when filing a detailed issue:
+
+```bash
+codewhale doctor --json
+```
+
+For authentication problems, check which source is winning: saved config,
+keyring, environment, or an explicit launch flag. A stale `DEEPSEEK_API_KEY`
+environment variable can override what you expected to use.
+
+For provider problems, confirm the active provider and model:
+
+```text
+/provider
+/model
+```
+
+For long or confusing sessions, use `/compact` to reduce context pressure, or
+start a fresh session in the same workspace and summarize what you need.
+
+When reporting an issue, include:
+
+- CodeWhale version.
+- Install method.
+- Operating system and terminal.
+- Provider and model.
+- The exact command or prompt.
+- Relevant doctor output.
+- Whether the problem happens in a fresh workspace.
+
+Do not paste API keys, private source code, or secrets into a public issue.
+
+Next: [OPERATIONS_RUNBOOK.md](OPERATIONS_RUNBOOK.md) has operational triage and
+recovery steps.
+
+## FAQ
+
+### Is CodeWhale only for DeepSeek?
+
+DeepSeek is the default and first-class route, but CodeWhale also supports
+other hosted and local OpenAI-compatible providers. Use `/provider` or
+`codewhale --provider <id>` to choose a provider. Keep the provider registry
+open when configuring a non-default route.
+
+### Which mode should I use first?
+
+Use Plan for unfamiliar code, Agent for normal implementation, and YOLO only
+for trusted repositories where automatic execution is acceptable.
+
+### Why does CodeWhale ask before running commands?
+
+Approvals are part of the safety model. Shell commands, paid tools, writes, and
+actions outside the expected workspace can have side effects. Approval prompts
+let you keep control while still letting the model do useful work.
+
+### Where is my config stored?
+
+New CodeWhale config uses `~/.codewhale/config.toml`. Legacy
+`~/.deepseek/config.toml` remains supported for compatibility. Project overlays
+can also affect behavior when a workspace config exists.
+
+### How do I keep costs predictable?
+
+Use `/model auto` for routing, choose a fixed model when you need a strict
+profile, and compact long sessions. For larger tasks, ask CodeWhale to plan
+before implementing so you do not spend tokens on the wrong path.
+
+### How do I continue previous work?
+
+CodeWhale saves sessions. Use the session picker or resume/continue CLI paths
+documented in the README and modes guide. For a risky experiment, fork the
+session before changing direction.
+
+### What should I do when the model gets confused?
+
+Stop and restate the goal, constraints, and current evidence. If the transcript
+is long, use `/compact` or start a fresh session with a short handoff. If the
+problem is operational, run `codewhale doctor` and inspect the reported config
+and provider state.
+
+### Should I put project rules in prompts or files?
+
+Use repository files for durable project rules and prompts for turn-specific
+intent. If a workflow repeats across projects, consider turning it into a
+skill.
+
+### Can CodeWhale edit files outside the current repository?
+
+That depends on workspace boundaries, sandbox settings, trust mode, and
+approval policy. For contribution work, keep instructions scoped to the current
+repository unless you intentionally need something else.
+
+### Where should I go after this guide?
+
+Read the focused reference for the thing you are changing. For most users, the
+next pages are install, configuration, providers, modes, keybindings, tools,
+and sub-agents.
+
+Next: [INSTALL.md](INSTALL.md), [CONFIGURATION.md](CONFIGURATION.md),
+[PROVIDERS.md](PROVIDERS.md), [MODES.md](MODES.md), and
+[TOOL_SURFACE.md](TOOL_SURFACE.md).
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 2a9fd17b..44aa6a54 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -12,17 +12,19 @@ If you just want the short version, see the
 
 ## 1. Supported platforms
 
-`codewhale-tui` ships prebuilt binaries for these
-platform/architecture combinations from v0.8.8 onward:
+CodeWhale ships matched `codewhale` and `codewhale-tui` prebuilt binaries for
+these platform/architecture combinations. Linux ARM64 is available from
+v0.8.8 onward; Linux RISC-V starts with the first release after v0.8.47.
 
 | Platform     | Architecture | npm install | `cargo install` | GitHub release asset                                  |
 | ------------ | ------------ | :---------: | :-------------: | ----------------------------------------------------- |
 | Linux        | x64 (x86_64) |     ✅      |       ✅        | `codewhale-linux-x64`, `codewhale-tui-linux-x64`        |
 | Linux        | arm64        |     ✅      |       ✅        | `codewhale-linux-arm64`, `codewhale-tui-linux-arm64`    |
+| Linux        | riscv64      |     ✅      |       ✅        | `codewhale-linux-riscv64`, `codewhale-tui-linux-riscv64`|
 | macOS        | x64          |     ✅      |       ✅        | `codewhale-macos-x64`, `codewhale-tui-macos-x64`        |
 | macOS        | arm64 (M-series) | ✅      |       ✅        | `codewhale-macos-arm64`, `codewhale-tui-macos-arm64`    |
 | Windows      | x64          |     ✅      |       ✅        | `codewhale-windows-x64.exe`, `codewhale-tui-windows-x64.exe` |
-| Other Linux (musl, riscv64, …) | — |   ❌¹    |       ✅²       | build from source                                     |
+| Other Linux (musl, other architectures) | — |   ❌¹    |       ✅²       | build from source                                     |
 | FreeBSD / OpenBSD              | — |   ❌      |       ✅²       | build from source                                     |
 
 ¹ The npm package will exit with a clear error and point you here.
@@ -49,7 +51,7 @@ systems such as Alpine should use [Build from source](#7-build-from-source).
 
 Official release binaries are published only from
 `https://github.com/Hmbown/CodeWhale/releases` and the npm package named
-`codewhale-tui`. Do not install release assets from look-alike repositories,
+`codewhale`. Do not install release assets from look-alike repositories,
 archives, or search-result mirrors unless you deliberately trust that mirror.
 
 Every GitHub release includes `codewhale-artifacts-sha256.txt`. If you download
@@ -266,6 +268,13 @@ chmod +x ~/.local/bin/codewhale ~/.local/bin/codewhale-tui
 codewhale --version
 ```
 
+> **macOS Gatekeeper note.** If you downloaded the binaries with a browser,
+> macOS may block them with "Apple cannot verify" warnings. Clear the quarantine
+> attribute on both binaries and retry:
+> ```bash
+> xattr -d com.apple.quarantine ~/.local/bin/codewhale ~/.local/bin/codewhale-tui 2>/dev/null || true
+> ```
+
 Verify integrity against the per-release SHA-256 manifest:
 
 ```bash
@@ -472,6 +481,9 @@ Cargo mirror setup in [Section 4](#4-install-via-cargo-any-tier-1-rust-target).
 assets. On networks where GitHub is blocked or unreliable, use the CNB source
 mirror instead and install both binaries from the release tag:
 
+To check the latest release without downloading or replacing binaries, run
+`codewhale update --check`.
+
 ```bash
 cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli --locked --force
 cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-tui     --locked --force
diff --git a/docs/LOCALIZATION.md b/docs/LOCALIZATION.md
index 0182055c..b16b433d 100644
--- a/docs/LOCALIZATION.md
+++ b/docs/LOCALIZATION.md
@@ -23,6 +23,8 @@ These locales are supported by `locale` in `settings.toml` and by `LANG` / `LC_A
 | `ja` | Japanese | Jpan | LTR | `en` | v0.7.6 must-have | Core TUI chrome | Covers composer placeholder/history search, help chrome, and `/config` chrome. |
 | `zh-Hans` | Chinese Simplified | Hans | LTR | `en` | v0.7.6 must-have | Core TUI chrome | `zh`, `zh-CN`, and `zh-Hans` resolve here. Traditional Chinese is not shipped. |
 | `pt-BR` | Portuguese (Brazil) | Latin | LTR | `en` | v0.7.6 must-have | Core TUI chrome | `pt` and `pt-PT` currently fall back to Brazilian Portuguese; European Portuguese is not separately shipped. |
+| `es-419` | Spanish (Latin America) | Latin | LTR | `en` | v0.7.6 must-have | Core TUI chrome | `es` and regional variants resolve here. |
+| `vi` | Vietnamese | Latin | LTR | `en` | v0.7.6 must-have | Core TUI chrome | Fully translated UI chrome, automated width tested. |
 
 Selection:
 
@@ -31,6 +33,8 @@ locale = "auto"     # default; checks LC_ALL, LC_MESSAGES, then LANG
 locale = "ja"
 locale = "zh-Hans"
 locale = "pt-BR"
+locale = "es-419"
+locale = "vi"
 ```
 
 Fallback:
@@ -52,12 +56,10 @@ These are not claimed as shipped translations in v0.7.6 unless a later change ad
 | `hi` | Hindi | Deva | LTR | Follow-up | Planned | `en` | Automated renderer sample only; native review preferred before shipping | Combining marks, cursor width, truncation |
 | `bn` | Bengali | Beng | LTR | Follow-up | Planned | `en` | Matrix only; native review required before shipping | Combining marks, line wrapping |
 | `id` | Indonesian | Latin | LTR | Follow-up | Planned | `en` | Matrix only; automated narrow-width snapshots and reviewer pass required | Longer labels than English |
-| `vi` | Vietnamese | Latin | LTR | Follow-up | Planned | `en` | Matrix only; automated width snapshots and reviewer pass required | Diacritics and wrapped labels |
 | `sw` | Swahili | Latin | LTR | Follow-up | Planned | `en` | Matrix only; native or fluent review required before shipping | Translation quality, longer command descriptions |
 | `ha` | Hausa | Latin | LTR | Follow-up | Planned | `en` | Matrix only; native or fluent review required before shipping | Diacritics and terminology |
 | `yo` | Yoruba | Latin | LTR | Follow-up | Planned | `en` | Matrix only; native or fluent review required before shipping | Tone marks and terminology |
 | `fil` | Filipino/Tagalog | Latin | LTR | Follow-up | Planned | `en` | Matrix only; source strings required before shipping | Terminology consistency |
-| `es-419` | Spanish (Latin America) | Latin | LTR | Follow-up | Planned | `en` | Matrix only; reviewer pass required before shipping | Regional terminology |
 | `fr` | French | Latin | LTR | Follow-up | Planned | `en` | Matrix only; reviewer pass required before shipping | African locale terminology varies |
 
 ## Message Coverage
diff --git a/docs/MODES.md b/docs/MODES.md
index 3da4f5b4..1a2763d9 100644
--- a/docs/MODES.md
+++ b/docs/MODES.md
@@ -19,7 +19,7 @@ Run `/mode` to open the mode picker, or switch directly with `/mode agent`,
 `/mode plan`, `/mode yolo`, `/mode 1`, `/mode 2`, or `/mode 3`.
 
 - **Plan**: design-first prompting. Read-only investigation tools stay available; shell and patch execution stay off. Use this when you want to think out loud and produce a plan to hand to a human (yourself later, or a reviewer).
-- **Agent**: multi-step tool use. Approvals for shell and paid tools (file writes are allowed without a prompt).
+- **Agent**: multi-step tool use. Shell execution (`exec_shell`, `task_shell_start`, `task_shell_wait`) requires `allow_shell = true` in config; approval prompts gate each call. File writes are allowed without a prompt.
 - **YOLO**: enables shell + trust mode and auto-approves all tools. Use only in trusted repos.
 
 All action-capable modes have access to persistent RLM sessions through `rlm_open`, `rlm_eval`, `rlm_configure`, and `rlm_close`. Inside an RLM Python REPL, `sub_query_batch` fans out 1-16 cheap parallel child calls pinned to `deepseek-v4-flash`. The model reaches for it when work is too large or repetitive for the parent transcript.
@@ -102,7 +102,7 @@ Run `codewhale --help` for the canonical list. Common flags:
 - `-r, --resume <ID|PREFIX|latest>`: resume a saved session
 - `-c, --continue`: resume the most recent session in this workspace
 - `--max-subagents <N>`: clamp to `1..=20`
-- `--mouse-capture` / `--no-mouse-capture`: opt in or out of internal mouse scrolling, transcript selection, right-click context actions, and transcript scrollbar dragging. Mouse capture is enabled by default on non-Windows terminals and on Windows Terminal/ConEmu/Cmder so drag selection copies only transcript text and stays scoped to the transcript pane; hold Shift while dragging or use `--no-mouse-capture` for raw terminal selection. It defaults off on legacy Windows console (CMD without `WT_SESSION` / `ConEmuPID`) and inside JetBrains JediTerm — PyCharm/IDEA/CLion/etc. — where the terminal advertises mouse support but forwards SGR mouse events as raw text (#878, #898). Use `--mouse-capture` to opt in anywhere it's defaulted off. Raw terminal selection may cross the right sidebar because the terminal, not the TUI, owns the selection.
+- `--mouse-capture` / `--no-mouse-capture`: opt in or out of internal mouse scrolling, transcript selection, right-click context actions, and transcript scrollbar dragging. Mouse capture is enabled by default on non-Windows terminals and on Windows Terminal/ConEmu/Cmder so drag selection copies only transcript text, removes visual wrap-column line breaks from paragraphs, and stays scoped to the transcript pane; hold Shift while dragging or use `--no-mouse-capture` for raw terminal selection. It defaults off on legacy Windows console (CMD without `WT_SESSION` / `ConEmuPID`) and inside JetBrains JediTerm — PyCharm/IDEA/CLion/etc. — where the terminal advertises mouse support but forwards SGR mouse events as raw text (#878, #898). Use `--mouse-capture` to opt in anywhere it's defaulted off. Raw terminal selection may cross the right sidebar and include visual wraps because the terminal, not the TUI, owns the selection.
 - `--profile <NAME>`: select config profile
 - `--config <PATH>`: config file path
 - `-v, --verbose`: verbose logging
diff --git a/docs/PROVIDERS.md b/docs/PROVIDERS.md
new file mode 100644
index 00000000..dad384d9
--- /dev/null
+++ b/docs/PROVIDERS.md
@@ -0,0 +1,236 @@
+# Provider Registry
+
+This registry describes provider behavior that is wired into the current
+CodeWhale codebase. It is intentionally conservative: shipped entries are
+limited to provider IDs, config keys, auth paths, base URLs, model resolution,
+and capability metadata that the code already knows about.
+
+DeepSeek remains the first-class default provider. NVIDIA NIM, Volcengine Ark,
+OpenRouter, Xiaomi MiMo, Novita, Fireworks, generic OpenAI-compatible endpoints,
+self-hosted runtimes, and Moonshot/Kimi are additive routes for running the
+same terminal harness against other hosted or local model endpoints. Hugging
+Face Inference Providers are a planned additive open-model routing layer; they
+are not a native provider in this checkout yet.
+
+Sources to keep in sync:
+
+- `crates/config/src/lib.rs` - shared provider IDs, defaults, env precedence.
+- `crates/tui/src/config.rs` - TUI provider IDs, provider capability metadata,
+  and provider-specific env handling.
+- `crates/agent/src/lib.rs` - static `ModelRegistry` used by
+  `codewhale model list` and `codewhale model resolve`.
+- `config.example.toml` and `docs/CONFIGURATION.md` - user-facing config
+  examples and environment variable reference.
+- `scripts/check-provider-registry.py` - drift check for canonical provider
+  IDs, live TUI provider IDs, TOML table names, static registry rows, and
+  documented defaults.
+
+## Provider Selection
+
+The canonical provider IDs are:
+
+`deepseek`, `nvidia-nim`, `openai`, `atlascloud`, `wanjie-ark`, `volcengine`,
+`openrouter`, `xiaomi-mimo`, `novita`, `fireworks`, `moonshot`, `sglang`,
+`vllm`, and `ollama`.
+
+Use any of these surfaces to select a provider:
+
+- CLI: `codewhale --provider <id>`
+- TUI: `/provider <id>` or the provider picker
+- Env: `CODEWHALE_PROVIDER=<id>`; `DEEPSEEK_PROVIDER=<id>` is the legacy alias
+- Config: `provider = "<id>"`
+
+`deepseek-cn`, `deepseek_china`, `deepseekcn`, and `deepseek-china` are accepted
+as legacy aliases for `deepseek`. They do not select a different official host;
+DeepSeek uses the same official API host worldwide.
+
+Fresh shared config writes to `~/.codewhale/config.toml`. Existing
+`~/.deepseek/config.toml` files are still read for compatibility.
+
+## Auth And Env Rules
+
+For hosted providers, `codewhale auth set --provider <id>` saves an API key for
+that provider. API-key environment variables are fallback inputs after saved
+config and keyring credentials; an explicit process-level `--api-key` still
+wins for that launch.
+
+For base URL and model selection, prefer:
+
+- `CODEWHALE_BASE_URL` / `CODEWHALE_MODEL` for the active provider.
+- Provider-specific base URL/model env vars when listed below.
+- `DEEPSEEK_BASE_URL`, `DEEPSEEK_MODEL`, and `DEEPSEEK_DEFAULT_TEXT_MODEL` as
+  legacy aliases.
+
+Non-local `http://` base URLs are rejected unless
+`DEEPSEEK_ALLOW_INSECURE_HTTP=1` is set. Loopback HTTP URLs are allowed for
+self-hosted runtimes.
+
+## Custom DeepSeek-Compatible Endpoints
+
+Most custom DeepSeek-compatible deployments can use an existing provider ID.
+Do not create `[providers.deepseek_custom]`; the provider table names are fixed.
+Instead, choose the closest shipped route and override its endpoint/model:
+
+- DeepSeek-compatible hosted API: keep `provider = "deepseek"` and set
+  `[providers.deepseek].base_url` plus `[providers.deepseek].model`, or launch
+  with `DEEPSEEK_BASE_URL` and `DEEPSEEK_MODEL`.
+- Generic OpenAI-compatible gateway: use `provider = "openai"` with
+  `[providers.openai].base_url` plus `[providers.openai].model`, or launch with
+  `OPENAI_BASE_URL` and `OPENAI_MODEL`.
+- Local OpenAI-compatible runtimes: use `provider = "vllm"`, `"sglang"`, or
+  `"ollama"` with the matching provider-specific base URL/model values.
+
+Example user config for a DeepSeek-compatible host:
+
+```toml
+provider = "deepseek"
+
+[providers.deepseek]
+api_key = "YOUR_API_KEY"
+base_url = "https://your-provider.example/v1"
+model = "deepseek-ai/DeepSeek-V4-Pro"
+```
+
+Example user config for a generic gateway:
+
+```toml
+provider = "openai"
+
+[providers.openai]
+api_key = "YOUR_GATEWAY_API_KEY"
+base_url = "https://gateway.example/v1"
+model = "your-deepseek-compatible-model"
+```
+
+Keep `provider`, `api_key`, and `base_url` in user config or process
+environment. Project-local config overlays intentionally cannot set those keys,
+so a repository cannot silently redirect prompts or credentials to another
+endpoint.
+
+## Shipped Providers
+
+| Provider ID | TOML table | Auth env | Base URL env and default | Default or static models | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `deepseek` | `[providers.deepseek]` | `DEEPSEEK_API_KEY` | `CODEWHALE_BASE_URL` / `DEEPSEEK_BASE_URL`; default `https://api.deepseek.com/beta` | `deepseek-v4-pro`, `deepseek-v4-flash`; compatibility aliases `deepseek-chat`, `deepseek-reasoner` | First-class default. Beta URL enables strict tool mode, chat prefix completion, and FIM completion. Set `https://api.deepseek.com` or `/v1` explicitly to opt out of beta-only features. |
+| `nvidia-nim` | `[providers.nvidia_nim]` | `NVIDIA_API_KEY`, `NVIDIA_NIM_API_KEY`, fallback `DEEPSEEK_API_KEY` | `NVIDIA_NIM_BASE_URL`, `NIM_BASE_URL`, `NVIDIA_BASE_URL`; default `https://integrate.api.nvidia.com/v1` | `deepseek-ai/deepseek-v4-pro`, `deepseek-ai/deepseek-v4-flash` | Hosted DeepSeek V4 through NVIDIA NIM. `NVIDIA_NIM_MODEL` is accepted by the TUI config path. |
+| `openai` | `[providers.openai]` | `OPENAI_API_KEY` | `OPENAI_BASE_URL`; default `https://api.openai.com/v1` | Registry entries: `deepseek-v4-pro`, `deepseek-v4-flash`; default config model `deepseek-v4-pro` | Generic OpenAI-compatible route for gateways and custom endpoints. Use this for explicit third-party OpenAI-compatible routes instead of inventing a new provider ID. `OPENAI_MODEL` is accepted. |
+| `atlascloud` | `[providers.atlascloud]` | `ATLASCLOUD_API_KEY` | `ATLASCLOUD_BASE_URL`; default `https://api.atlascloud.ai/v1` | Default config model `deepseek-ai/deepseek-v4-flash` | OpenAI-compatible hosted route. `ATLASCLOUD_MODEL` is accepted by the TUI config path. The static `ModelRegistry` does not currently list AtlasCloud rows. |
+| `wanjie-ark` | `[providers.wanjie_ark]` | `WANJIE_ARK_API_KEY`, `WANJIE_API_KEY`, `WANJIE_MAAS_API_KEY` | `WANJIE_ARK_BASE_URL`, `WANJIE_BASE_URL`, `WANJIE_MAAS_BASE_URL`; default `https://maas-openapi.wanjiedata.com/api/v1` | `deepseek-reasoner` | OpenAI-compatible hosted route. `WANJIE_ARK_MODEL`, `WANJIE_MODEL`, and `WANJIE_MAAS_MODEL` are accepted. |
+| `volcengine` | `[providers.volcengine]` | `VOLCENGINE_API_KEY`, `VOLCENGINE_ARK_API_KEY`, `ARK_API_KEY` | `VOLCENGINE_BASE_URL`, `VOLCENGINE_ARK_BASE_URL`, `ARK_BASE_URL`; default `https://ark.cn-beijing.volces.com/api/coding/v3` | `DeepSeek-V4-Pro`, `DeepSeek-V4-Flash` | Volcengine/Volcano Engine Ark OpenAI-compatible coding endpoint. `VOLCENGINE_MODEL` and `VOLCENGINE_ARK_MODEL` are accepted. |
+| `openrouter` | `[providers.openrouter]` | `OPENROUTER_API_KEY` | `OPENROUTER_BASE_URL`; default `https://openrouter.ai/api/v1` | `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash` | Additive open-model routing layer. It does not replace DeepSeek; it lets users route supported model IDs through OpenRouter when they choose it. |
+| `xiaomi-mimo` | `[providers.xiaomi_mimo]` | `XIAOMI_MIMO_API_KEY`, `MIMO_API_KEY` | `XIAOMI_MIMO_BASE_URL`, `MIMO_BASE_URL`; default `https://api.xiaomimimo.com/v1` | `mimo-v2.5-pro`, `mimo-v2.5` | Xiaomi MiMo OpenAI-compatible chat completions route. It sends `max_completion_tokens` and uses MiMo's `thinking` field for reasoning control. |
+| `novita` | `[providers.novita]` | `NOVITA_API_KEY` | `NOVITA_BASE_URL`; default `https://api.novita.ai/v1` | `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash` | OpenAI-compatible hosted route for DeepSeek model IDs. Use config or `CODEWHALE_MODEL` / `DEEPSEEK_MODEL` for model overrides. |
+| `fireworks` | `[providers.fireworks]` | `FIREWORKS_API_KEY` | `FIREWORKS_BASE_URL`; default `https://api.fireworks.ai/inference/v1` | `accounts/fireworks/models/deepseek-v4-pro` | OpenAI-compatible hosted route. Use config or `CODEWHALE_MODEL` / `DEEPSEEK_MODEL` for model overrides. |
+| `moonshot` | `[providers.moonshot]` | `MOONSHOT_API_KEY`, `KIMI_API_KEY` | `MOONSHOT_BASE_URL`, `KIMI_BASE_URL`; default `https://api.moonshot.ai/v1` | `kimi-k2.6`; Kimi Code path uses `kimi-for-coding` at `https://api.kimi.com/coding/v1` | Moonshot/Kimi route. `MOONSHOT_MODEL`, `KIMI_MODEL_NAME`, and `KIMI_MODEL` are accepted. `[providers.moonshot] auth_mode = "kimi_oauth"` reads Kimi CLI OAuth credentials when present. |
+| `sglang` | `[providers.sglang]` | Optional `SGLANG_API_KEY` | `SGLANG_BASE_URL`; default `http://localhost:30000/v1` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | Self-hosted OpenAI-compatible route. Localhost deployments commonly omit auth. `SGLANG_MODEL` is accepted. |
+| `vllm` | `[providers.vllm]` | Optional `VLLM_API_KEY` | `VLLM_BASE_URL`; default `http://localhost:8000/v1` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | Self-hosted vLLM OpenAI-compatible route. Localhost deployments commonly omit auth. `VLLM_MODEL` is accepted. |
+| `ollama` | `[providers.ollama]` | Optional `OLLAMA_API_KEY` | `OLLAMA_BASE_URL`; default `http://localhost:11434/v1` | `deepseek-coder:1.3b`; provider-hinted custom tags pass through | Self-hosted Ollama OpenAI-compatible route. Localhost deployments commonly omit auth. `OLLAMA_MODEL` is accepted. |
+
+### Xiaomi MiMo Notes
+
+`xiaomi-mimo` defaults to `mimo-v2.5-pro` for long-context reasoning and coding
+work, while the static registry also exposes `mimo-v2.5`. Xiaomi's current
+[image-understanding guide](https://platform.xiaomimimo.com/docs/en-US/usage-guide/multimodal-understanding/image-understanding)
+includes `mimo-v2.5` for image input. CodeWhale exposes image analysis through the
+separate `[vision_model]` / `image_analyze` path; set that model to
+`mimo-v2.5` when using MiMo for vision.
+
+## Static Model Registry
+
+`codewhale model list` and `codewhale model resolve` use the static registry in
+`crates/agent/src/lib.rs`. This is not the same as live `/models` discovery.
+Use `/models` or `codewhale models` to fetch model IDs from the active API
+endpoint when the endpoint supports model listing.
+
+| Provider | Static registry entries | Tool calls | Registry reasoning flag |
+| --- | --- | --- | --- |
+| `deepseek` | `deepseek-v4-pro`, `deepseek-v4-flash` | yes | yes |
+| `nvidia-nim` | `deepseek-ai/deepseek-v4-pro`, `deepseek-ai/deepseek-v4-flash` | yes | yes |
+| `openai` | `deepseek-v4-pro`, `deepseek-v4-flash` | yes | yes |
+| `wanjie-ark` | `deepseek-reasoner` | yes | yes |
+| `volcengine` | `DeepSeek-V4-Pro`, `DeepSeek-V4-Flash` | yes | yes |
+| `openrouter` | `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash` | yes | yes |
+| `xiaomi-mimo` | `mimo-v2.5-pro`, `mimo-v2.5` | yes | yes |
+| `novita` | `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash` | yes | yes |
+| `fireworks` | `accounts/fireworks/models/deepseek-v4-pro` | yes | yes |
+| `moonshot` | `kimi-k2.6` | yes | yes |
+| `sglang` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | yes | yes |
+| `vllm` | `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` | yes | yes |
+| `ollama` | `deepseek-coder:1.3b`; custom tags pass through when provider hint is `ollama` | yes | no |
+
+The registry currently has no AtlasCloud entry even though AtlasCloud is a
+supported provider in config and TUI selection. AtlasCloud should use the
+configured model or live model listing.
+
+## Capability Metadata
+
+`codewhale-tui doctor --json` exposes the `capability` object. It is static
+metadata, not a live API probe. Current fields are:
+
+`resolved_provider`, `resolved_model`, `context_window`, `max_output`,
+`thinking_supported`, `cache_telemetry_supported`, and `request_payload_mode`.
+
+All shipped providers use the Chat Completions request payload mode today.
+
+| Provider/model class | Context window | Max output metadata | Thinking support | Cache telemetry | FIM endpoint |
+| --- | --- | --- | --- | --- | --- |
+| DeepSeek V4 (`deepseek-v4-pro`, `deepseek-v4-flash`) | 1,000,000 | 384,000 | yes | yes | DeepSeek beta only |
+| DeepSeek compatibility aliases (`deepseek-chat`, `deepseek-reasoner`) | 1,000,000 | 384,000 | yes | yes | DeepSeek beta only |
+| NVIDIA NIM V4 registry models | 1,000,000 | 384,000 | yes | yes | not documented in code |
+| OpenRouter, Novita, Fireworks, Volcengine Ark, SGLang, and vLLM V4 model IDs | 1,000,000 | 384,000 | yes | Volcengine only | not documented in code |
+| Xiaomi MiMo models | 1,000,000 | 128,000 | yes | no | not documented in code |
+| Wanjie Ark `reasoner` / `r1` model IDs | 128,000 | 4,096 | yes | no | not documented in code |
+| Generic `openai`, AtlasCloud, and Moonshot/Kimi | 128,000 | 4,096 | no in doctor capability metadata | no | not documented in code |
+| Ollama | 8,192 | 4,096 | no | no | not documented in code |
+| Other recognized DeepSeek model IDs | 128,000 unless the model name carries an explicit `Nk` hint | 4,096 | no unless V4/reasoner logic matches | DeepSeek/NIM only | DeepSeek beta only |
+
+Tool-call support is tracked separately by the static `ModelRegistry` and by
+the endpoint's ability to accept OpenAI-compatible `tools` payloads. A custom
+OpenAI-compatible or local endpoint can still reject tool calls even if
+CodeWhale can send the schema.
+
+DeepSeek compatibility aliases `deepseek-chat` and `deepseek-reasoner` map to
+`deepseek-v4-flash` capability metadata and are scheduled to retire on
+2026-07-24 at 2026-07-24T15:59:00Z.
+
+## Drift Check
+
+Run this before changing provider IDs, provider TOML tables, static model
+registry rows, or provider default strings:
+
+```bash
+python3 scripts/check-provider-registry.py
+```
+
+The check fails when:
+
+- `docs/PROVIDERS.md` omits a canonical `ProviderKind::as_str()` ID.
+- `crates/tui/src/config.rs` `ApiProvider::as_str()` diverges from
+  `ProviderKind::as_str()` except for the explicit `deepseek-cn` legacy alias.
+- The shipped-provider table omits or adds a `[providers.*]` TOML table.
+- The static model registry table drifts from providers used by
+  `crates/agent/src/lib.rs`.
+- A provider default model or base URL constant in `crates/tui/src/config.rs`
+  is no longer mentioned here.
+
+## Planned, Not Shipped Yet
+
+These items belong to the v0.8.47 provider-abstraction milestone or related
+provider docs work, but they are not native shipped behavior in this checkout:
+
+- A unified `Provider` trait in `codewhale-agent` that owns env precedence,
+  secret resolution, base URL normalization, auth-header construction, and
+  provider metadata. Those responsibilities are still split across
+  `crates/config`, `crates/secrets`, and `crates/tui/src/client.rs`.
+- A native Hugging Face provider such as `[providers.huggingface]`.
+- Native Hugging Face auth envs such as `HF_TOKEN` or `HUGGINGFACE_API_KEY`.
+- A default Hugging Face router base URL such as
+  `https://router.huggingface.co/v1`.
+- Hugging Face model passport metadata in the picker, including license, base
+  model, context length, chat template, tool-call support, reasoning support,
+  and gated/private status.
+
+Until native Hugging Face support lands, users can only reach an explicitly
+configured Hugging Face-compatible OpenAI route through the generic `openai`
+provider. That is an explicit user-selected route, not built-in Hub discovery
+or a replacement for DeepSeek.
diff --git a/docs/REVIEW_PIPELINE.md b/docs/REVIEW_PIPELINE.md
new file mode 100644
index 00000000..95af4eca
--- /dev/null
+++ b/docs/REVIEW_PIPELINE.md
@@ -0,0 +1,84 @@
+\# CodeWhale Review Pipeline
+
+
+
+Welcome to CodeWhale! We receive a high volume of community PRs. To ensure a smooth and fast review process, please review our pipeline expectations below. 
+
+
+
+\## 1. CI Gates (Pre-Review Checklist)
+
+Before a maintainer reviews your PR, it must pass our continuous integration (CI) checks. 
+
+
+
+\*\*Required Checks (Must Pass):\*\*
+
+Please run these locally before pushing your code to avoid CI failures:
+
+\* \*\*Format:\*\* `cargo fmt --all -- --check`
+
+\* \*\*Linting:\*\* `cargo clippy --workspace --all-targets --all-features`
+
+\* \*\*Tests:\*\* `cargo test --workspace --all-features --locked`
+
+
+
+\*\*Informational Checks:\*\*
+
+Checks from \*\*Greptile\*\* and \*\*GitGuardian\*\* are informational. If they flag something, review it, but they do not strictly block a review on their own unless a secret is leaked.
+
+
+
+\## 2. Common Failure Modes \& Local Fixes
+
+If CI fails, it is usually one of these three reasons:
+
+\* \*\*Version Drift (`Cargo.lock` out of date):\*\* Run `cargo update` or `cargo build` locally to update the lockfile and commit the changes.
+
+\* \*\*Lint Failures:\*\* Check the clippy warnings from the command above and fix the specific lines flagged.
+
+\* \*\*Windows Test Flakiness:\*\* Occasionally, tests may time out on Windows runners. If you are confident your code didn't break it, leave a comment asking a maintainer to re-trigger the CI.
+
+
+
+\## 3. PR Etiquette
+
+To help us review your code quickly, please adhere to the following:
+
+\* \*\*One Concern Per PR:\*\* Keep diffs highly focused. Do not mix refactoring with new feature additions.
+
+\* \*\*Link the Issue:\*\* Always include `Closes #N` (replace N with the issue number) in your PR description so GitHub automatically links them.
+
+\* \*\*Rebase:\*\* Always rebase your branch onto the latest `main` branch before requesting a review.
+
+
+
+\## 4. The Review Workflow
+
+Once CI is green, your PR enters the review queue.
+
+\* \*\*Who reviews:\*\* Core maintainers will review the PR. 
+
+\* \*\*`autonomous-ready` Label:\*\* If a maintainer applies this label, it means the PR is approved in concept and is queued for our automated integration system.
+
+\* \*\*The Nightly Loop:\*\* We run extensive integration loops overnight. If your PR is approved, it may wait for this nightly loop before final merging to ensure system stability.
+
+
+
+\## 5. Post-Merge Actions
+
+After your code is merged, the following automated actions occur:
+
+\* `CHANGELOG.md` is updated.
+
+\* `npm` wrappers are synced.
+
+\* Binary rebuilds are triggered for all platforms.
+
+\* Website and documentation are synced with your new changes.
+
+
+
+Thank you for contributing to CodeWhale!
+
diff --git a/docs/RUNTIME_API.md b/docs/RUNTIME_API.md
index 504154f0..d7ec8331 100644
--- a/docs/RUNTIME_API.md
+++ b/docs/RUNTIME_API.md
@@ -117,6 +117,7 @@ codewhale doctor --json
 
 ```bash
 codewhale serve --http [--host 127.0.0.1] [--port 7878] [--workers 2] [--auth-token TOKEN]
+codewhale serve --mobile [--host 0.0.0.0] [--port 7878] [--auth-token TOKEN]
 ```
 
 Defaults: host `127.0.0.1`, port `7878`, 2 workers (clamped 1–8).
@@ -124,16 +125,35 @@ Defaults: host `127.0.0.1`, port `7878`, 2 workers (clamped 1–8).
 The server binds to `localhost` by default. Configuration is via CLI flags —
 there is no `[app_server]` config section.
 
-By default, existing local behavior is unchanged and `/v1/*` routes are not
-authenticated. To require a bearer token for `/v1/*` routes, pass
-`--auth-token TOKEN` or set `DEEPSEEK_RUNTIME_TOKEN=TOKEN` before starting the
-server. `/health` remains public for local process supervision and readiness
-checks.
+`/v1/*` routes require a bearer token unless `--insecure` is explicitly set.
+Pass `--auth-token TOKEN` or set `DEEPSEEK_RUNTIME_TOKEN=TOKEN` before starting
+the server. If neither is set, the process generates a one-time token and prints
+it at startup. `/health` and `/v1/runtime/info` remain public for local
+supervision and bootstrap. `/mobile` returns 404 when mobile mode is disabled;
+when mobile mode is enabled and auth is enabled, `/mobile` returns 401 unless
+the request supplies the runtime token.
 
 Authenticated clients can provide the token as `Authorization: Bearer TOKEN`,
 `X-DeepSeek-Runtime-Token: TOKEN`, or `?token=TOKEN` for EventSource-style
 clients that cannot set custom headers.
 
+### Mobile control page
+
+`codewhale serve --mobile` starts the same HTTP/SSE runtime API and serves a
+phone-friendly control page at `/mobile`. When the bind host is left at the
+default, mobile mode binds to `0.0.0.0`, prints a warning, and prints local/LAN
+URLs. Pass `--host 127.0.0.1` to keep the mobile page loopback-only. If a
+runtime token is generated or supplied, the printed mobile URL includes it as a
+query parameter; the page stores it locally and removes it from the address bar.
+The static HTML page contains no secrets, but it is still token-gated when auth
+is enabled so unauthenticated LAN clients cannot fingerprint the mobile surface.
+
+The mobile page can list/create threads, send prompts, follow live SSE events,
+steer or interrupt an active turn, and resolve normal tool approvals through
+`POST /v1/approvals/{approval_id}`. It is still a local/LAN convenience surface:
+do not expose it directly to the public internet without TLS and a trusted
+fronting layer.
+
 ### Endpoints
 
 **Health**
@@ -188,6 +208,10 @@ accept an empty string to clear a previously-set value. Added in v0.8.10 (#562):
 - `POST /v1/threads/{id}/turns/{turn_id}/interrupt`
 - `POST /v1/threads/{id}/compact` (manual compaction)
 
+**Approvals**
+- `POST /v1/approvals/{approval_id}` with body
+  `{ "decision": "allow" | "deny", "remember": false }`
+
 **Events** (SSE replay + live stream)
 - `GET /v1/threads/{id}/events?since_seq=<u64>`
 
@@ -306,13 +330,16 @@ The SSE event payload shape:
 Common event names: `thread.started`, `thread.forked`, `turn.started`,
 `turn.lifecycle`, `turn.steered`, `turn.interrupt_requested`,
 `turn.completed`, `item.started`, `item.delta`, `item.completed`,
-`item.failed`, `item.interrupted`, `approval.required`, `sandbox.denied`,
-`coherence.state`.
+`item.failed`, `item.interrupted`, `approval.required`, `approval.decided`,
+`approval.timeout`, `sandbox.denied`, `coherence.state`.
 
 ## Security boundary
 
-- **Localhost only**. The server binds to `127.0.0.1` by default. Set
-  `--host 0.0.0.0` only when you have a reverse-proxy / VPN that
+- **Localhost by default**. The server binds to `127.0.0.1` by default.
+  `--mobile` binds to `0.0.0.0` when no host is supplied so phones on the same
+  LAN can reach it, and the CLI prints a warning for that rebind. Pass
+  `--host 127.0.0.1` for a loopback-only mobile page. Set a non-loopback host
+  only when you trust the network path or have a reverse-proxy / VPN that
   authenticates. The runtime does not provide user isolation or TLS.
 - **Optional token guard**. `--auth-token` or `DEEPSEEK_RUNTIME_TOKEN`
   requires a matching bearer token for `/v1/*` routes. This is a local
diff --git a/docs/SANDBOX.md b/docs/SANDBOX.md
new file mode 100644
index 00000000..cf90db1c
--- /dev/null
+++ b/docs/SANDBOX.md
@@ -0,0 +1,271 @@
+# Sandbox threat model
+
+CodeWhale executes shell commands spawned by AI reasoning. The sandbox
+module restricts what those commands can do to the host system. This
+document describes what each platform's sandbox actually enforces,
+what is best-effort, and what is explicitly out of scope.
+
+## Platform overview
+
+| Mechanism | Platform | Type | Status |
+|---|---|---|---|
+| Seatbelt | macOS | Mandatory access control | Enforced |
+| Landlock | Linux | Filesystem access control | Enforced |
+| seccomp BPF | Linux | Syscall filter | Enforced |
+| Process hardening | Linux | Kernel prctl / rlimit | Enforced |
+| Bubblewrap (bwrap) | Linux | Namespace isolation | Optional |
+| Windows Job Object | Windows | Process-tree containment | v1 (PR #2220) |
+
+## Threat model: what each layer addresses
+
+### 1. Process hardening (Linux only)
+
+**When it runs:** Before any threads are spawned, before Tokio boots,
+before any data is loaded into memory.
+
+**What it does:**
+
+- `PR_SET_DUMPABLE=0` — prevents ptrace, makes `/proc/<pid>/` root-owned
+- `PR_SET_NO_NEW_PRIVS=1` — irreversible; no child can ever gain privileges
+- `RLIMIT_CORE=0` — no core dumps, so sensitive data never hits disk
+
+**What it protects against:**
+- Process inspection via ptrace/strace/gdb
+- Privilege escalation via setuid/setgid/fscaps
+- Core dumps leaking API keys, tokens, prompt content
+
+**What it does NOT protect against:**
+- A compromised child reading its parent's `/proc/<pid>/mem` (already blocked
+  by `PR_SET_DUMPABLE=0` making `/proc/<pid>/` root-owned)
+- Kernel exploits that bypass prctl
+
+### 2. Landlock (Linux, kernel 5.13+)
+
+**When it runs:** Applied to each child process at spawn time via a
+helper script or `landlock_restrict_self`. Only restrictable by the
+process itself — parent cannot force Landlock on a child.
+
+**What it does:**
+- Restricts filesystem access to a whitelist of paths
+- Handles: `EXECUTE`, `READ_FILE`, `READ_DIR`, `WRITE_FILE`, `REMOVE_DIR`,
+  `REMOVE_FILE`, `MAKE_DIR`, `MAKE_REG`, `MAKE_SYM`, `TRUNCATE`
+
+**What it protects against:**
+- Reading files outside the workspace (e.g., `/etc/passwd`, `~/.ssh`)
+- Writing to system directories (`/usr`, `/bin`, `/lib`)
+- Creating or deleting files in protected locations
+
+**What it does NOT protect against:**
+- Network access (Landlock is filesystem-only)
+- Process inspection (use seccomp for this)
+- Reading files that are already mapped (Landlock applies at `open()` time)
+
+**Detection:** `detect_denial()` checks stderr for `Permission denied`,
+`Operation not permitted`, `EACCES`, `EPERM`.
+
+### 3. seccomp BPF (Linux only)
+
+**When it runs:** Installed via `prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER)`
+on the child process.
+
+**What it does:**
+- Whitelist of ~100 safe syscalls (file I/O, memory, process, IPC,
+  synchronization, signals, time)
+- **Explicitly denied:** `ptrace`, `mount`, `umount2`, `kexec_load`,
+  `kexec_file_load`, `init_module`, `finit_module`, `delete_module`,
+  `bpf`, `reboot`, `swapon`, `swapoff`, `pivot_root`,
+  `setuid`/`setgid`/`setreuid`/`setregid`/`setresuid`/`setresgid`,
+  `personality`
+- Any syscall not on the whitelist → `SECCOMP_RET_KILL_PROCESS` (SIGSYS)
+
+**What it protects against:**
+- Process hijacking via ptrace
+- Mounting filesystems (bypassing Landlock read-only restrictions)
+- Loading kernel modules
+- Loading BPF programs (would bypass seccomp itself!)
+- Rebooting the system
+- Privilege changes via setuid/setgid
+
+**What it does NOT protect against:**
+- Legitimate use of allowed syscalls for malicious purposes
+- Side-channel attacks via allowed syscalls (e.g., timing)
+
+**Detection:** `detect_denial()` checks exit code 31 (SIGSYS) or stderr
+for `Bad system call`, `bad system call`, `SIGSYS`, `seccomp`.
+
+### 4. Bubblewrap / bwrap (Linux, optional)
+
+**When it runs:** If `/usr/bin/bwrap` is present AND the config key
+`[sandbox] prefer_bwrap = true` is set. Runs as an outer wrapper around
+the child command.
+
+**What it does:**
+- Creates a new mount namespace with `--unshare-all`
+- Read-only bind-mounts the entire root filesystem
+- Bind-mounts the workspace directory with read-write access
+- Changes into the workspace with `--chdir`
+
+**What it protects against:**
+- Any filesystem write outside the workspace (stronger than Landlock alone
+  because it's enforced at the namespace level, not just filesystem access)
+- Accidental modification of system files
+
+**What it does NOT protect against:**
+- Network access (bwrap does not create a network namespace by default with
+  `--unshare-all`; the child still has full network access)
+- Process inspection
+- Memory attacks
+
+**Installation:** User must install bubblewrap themselves:
+- Ubuntu/Debian: `apt install bubblewrap`
+- Fedora: `dnf install bubblewrap`
+- Arch: `pacman -S bubblewrap`
+
+CodeWhale does NOT vendor bwrap.
+
+**Fallback:** If bwrap is not installed, the sandbox falls back to Landlock
+only.
+
+### 5. Seatbelt (macOS)
+
+**When it runs:** Applied via the `sandbox-exec` wrapper command. The
+seatbelt profile is generated dynamically based on the `SandboxPolicy`.
+
+**What it does:**
+- Restricts filesystem access based on the policy profile
+- Can restrict network access (when `network_access: false`)
+
+**What it protects against:**
+- Reading/writing files outside allowed paths
+- Network connections (when configured)
+
+**What it does NOT protect against:**
+- Process inspection (Seatbelt does not block ptrace)
+- Syscall-level attacks
+
+**Detection:** Checks stderr for `file-write` and `network` denial patterns.
+
+### 6. Windows Job Object (v1, PR #2220)
+
+**When it runs:** Applied at process spawn time via
+`PROC_THREAD_ATTRIBUTE_JOB_LIST` and restricted token assignment.
+
+**What it does (v1):**
+- Job Object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` — all child
+  processes terminate when the parent exits
+- Memory cap: 1 GB per process, 2 GB per job
+- Active process limit: 64
+- UI restrictions: no desktop handle access
+- Restricted token: drops Administrators group SID, sets medium-low
+  integrity level
+
+**What is deferred (v2):**
+- WFP (Windows Filtering Platform) firewall rules — network is open in v1
+- Filesystem ACL integration at spawn time (stub exists)
+- AppContainer isolation
+- Registry key isolation
+
+**Detection:** Checks stderr for `Access is denied`, `STATUS_ACCESS_DENIED`,
+`ERROR_ACCESS_DENIED`, `ERROR_PRIVILEGE_NOT_HELD`,
+`ERROR_ACCESS_DISABLED_BY_POLICY`, and integrity/AppContainer patterns.
+
+## Defense in depth
+
+The Linux sandbox applies layers in order:
+
+```
+Process hardening (prctl)    ← before threads
+    ↓
+Landlock (filesystem)        ← at child spawn
+    ↓
+seccomp BPF (syscalls)       ← at child spawn
+    ↓
+bwrap (namespace isolation)  ← optional outer wrapper
+```
+
+Each layer addresses a different threat surface. seccomp cannot protect the
+filesystem (that's Landlock's job). Landlock cannot stop ptrace (that's
+seccomp + PR_SET_DUMPABLE). bwrap adds namespace-level isolation that
+neither Landlock nor seccomp can provide.
+
+## Configuration
+
+Relevant config keys in `~/.codewhale/config.toml`:
+
+```toml
+# Sandbox policy mode
+sandbox_mode = "workspace-write"  # read-only | workspace-write | danger-full-access | external-sandbox
+
+# Linux bubblewrap passthrough
+prefer_bwrap = false              # requires `bubblewrap` package installed
+
+# External sandbox backend
+sandbox_backend = "none"          # "none" or "opensandbox"
+sandbox_url = "http://localhost:8080"
+sandbox_api_key = "YOUR_API_KEY"
+```
+
+Environment variable overrides:
+
+- `DEEPSEEK_SANDBOX_MODE` → `sandbox_mode`
+- `DEEPSEEK_PREFER_BWRAP=true` → `prefer_bwrap`
+- `DEEPSEEK_SANDBOX_BACKEND` → `sandbox_backend`
+- `DEEPSEEK_SANDBOX_URL` → `sandbox_url`
+- `DEEPSEEK_SANDBOX_API_KEY` → `sandbox_api_key`
+
+## Detecting sandbox denials
+
+When a command fails, the sandbox manager checks for denial patterns:
+
+| Platform | Denial mechanism | Exit code | Stderr patterns |
+|---|---|---|---|
+| macOS Seatbelt | sandbox-exec violation | non-zero | `file-write`, `network` |
+| Linux Landlock | EACCES / EPERM | non-zero | `Permission denied`, `Operation not permitted` |
+| Linux seccomp | SIGSYS (31) | 31 or 159 | `Bad system call`, `SIGSYS` |
+| Linux bwrap | Mount/namespace failure | non-zero | varies |
+| Windows | Access denied / privilege | non-zero | `Access is denied`, `ERROR_PRIVILEGE_NOT_HELD` |
+
+The `was_denied()` method on `SandboxManager` aggregates all platform-specific
+checks. The `denial_message()` method returns a human-readable explanation.
+
+## Limitations
+
+### What the sandbox does NOT protect against
+
+- **Network attacks** — only macOS Seatbelt can block network; Linux and
+  Windows v1 leave network open
+- **Memory attacks** — no platform prevents a child process from reading
+  its own memory or exploiting memory corruption bugs
+- **Timing side channels** — allowed syscalls on Linux can be used for
+  timing-based information leaks
+- **Resource exhaustion** — the Linux job object limits memory and process
+  count, but does not limit CPU, file descriptors, or disk I/O
+- **Kernel vulnerabilities** — if the kernel itself has a vulnerability,
+  the sandbox cannot prevent exploitation (this applies to all platforms)
+- **Supply chain** — if the child process downloads and executes untrusted
+  code, the sandbox limits what that code can do, but does not prevent the
+  download
+
+### Platform-specific gaps
+
+- **Linux:** Landlock only protects filesystem access. seccomp adds syscall
+  filtering but uses a whitelist that may need updates for new syscalls.
+- **macOS:** Seatbelt profiles are generated at runtime. A misconfigured
+  profile could be too permissive.
+- **Windows v1:** No filesystem ACL enforcement at spawn time. Network is
+  fully open. Job Object is process-tree only.
+
+## Related
+
+- `crates/tui/src/sandbox/` — implementation
+- `crates/config/src/lib.rs` — config keys
+- `crates/tui/src/tools/diagnostics.rs` — `diagnostics` tool reports
+  `sandbox_available`, `sandbox_type`, `bwrap_available`, `cgroup_version`
+- `config.example.toml` — annotated config reference
+- Issue #2180 — this document
+- Issue #2182 — seccomp filter implementation
+- Issue #2183 — process hardening
+- Issue #2184 — bwrap passthrough
+- Issue #2185 — Windows Job Object v1
+- Issue #2186 — SandboxExecutor trait unification
+- Issue #2187 — sandbox parity tests
diff --git a/docs/TOOL_SURFACE.md b/docs/TOOL_SURFACE.md
index 1038b93e..36933b0d 100644
--- a/docs/TOOL_SURFACE.md
+++ b/docs/TOOL_SURFACE.md
@@ -35,7 +35,7 @@ chosen over the available shell equivalent. Companion to `crates/tui/src/prompts
 |---|---|
 | `grep_files` | Regex search file contents within the workspace; structured matches + context lines. Pure-Rust (`regex` crate), no `rg`/`grep` shell-out. |
 | `file_search` | Fuzzy-match filenames (not contents). Use when you know roughly the name. |
-| `web_search` | Bing by default; DuckDuckGo, Tavily, and Bocha are selectable in config. Ranked snippets + `ref_id` for citation. |
+| `web_search` | DuckDuckGo by default with Bing fallback; Bing, Tavily, Bocha, Metaso, and Baidu are selectable in config. Ranked snippets + `ref_id` for citation. |
 | `fetch_url` | Direct HTTP GET on a known URL. Faster than `web_search` when the link is already known. HTML stripped to text by default. |
 
 ### Shell
diff --git a/docs/examples/Dockerfile.toolbox b/docs/examples/Dockerfile.toolbox
new file mode 100644
index 00000000..fab0b73e
--- /dev/null
+++ b/docs/examples/Dockerfile.toolbox
@@ -0,0 +1,29 @@
+# syntax=docker/dockerfile:1
+#
+# Opt-in CodeWhale toolbox image.
+#
+# The published ghcr.io/hmbown/codewhale:latest image intentionally stays
+# minimal, non-root, and without passwordless sudo. Use this Dockerfile only for
+# workspaces where you deliberately want package installation, custom CA setup,
+# or project-specific build tools inside the container.
+#
+# Example:
+#   docker build -f docs/examples/Dockerfile.toolbox \
+#     --build-arg CODEWHALE_IMAGE=ghcr.io/hmbown/codewhale:vX.Y.Z \
+#     --build-arg TOOLBOX_PACKAGES="git openssh-client curl build-essential pkg-config python3 python3-pip nodejs npm" \
+#     -t codewhale-toolbox:my-project .
+
+ARG CODEWHALE_IMAGE=ghcr.io/hmbown/codewhale:latest
+FROM ${CODEWHALE_IMAGE}
+
+USER root
+
+ARG TOOLBOX_PACKAGES="git openssh-client curl build-essential pkg-config python3 python3-pip nodejs npm"
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends sudo ${TOOLBOX_PACKAGES} \
+    && rm -rf /var/lib/apt/lists/* \
+    && printf '%s\n' 'codewhale ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/codewhale-nopasswd \
+    && chmod 0440 /etc/sudoers.d/codewhale-nopasswd
+
+USER codewhale
+WORKDIR /workspace
diff --git a/docs/examples/compose.toolbox.yml b/docs/examples/compose.toolbox.yml
new file mode 100644
index 00000000..49b1451e
--- /dev/null
+++ b/docs/examples/compose.toolbox.yml
@@ -0,0 +1,40 @@
+# Opt-in CodeWhale toolbox workflow.
+#
+# Usage:
+#   CODEWHALE_IMAGE=ghcr.io/hmbown/codewhale:vX.Y.Z \
+#   CODEWHALE_TOOLBOX_IMAGE=codewhale-toolbox:my-project \
+#   CODEWHALE_HOME_VOLUME=codewhale-my-project-home \
+#   CODEWHALE_WORKSPACE="$PWD" \
+#   docker compose -f docs/examples/compose.toolbox.yml run --rm codewhale
+#
+# Keep CODEWHALE_HOME_VOLUME distinct per project so sessions, config, skills,
+# memory, and queued work do not bleed across workspaces.
+
+services:
+  codewhale:
+    image: ${CODEWHALE_TOOLBOX_IMAGE:-codewhale-toolbox:local}
+    build:
+      context: ../..
+      dockerfile: docs/examples/Dockerfile.toolbox
+      args:
+        CODEWHALE_IMAGE: ${CODEWHALE_IMAGE:-ghcr.io/hmbown/codewhale:latest}
+        TOOLBOX_PACKAGES: ${TOOLBOX_PACKAGES:-git openssh-client curl build-essential pkg-config python3 python3-pip nodejs npm}
+    environment:
+      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY:?set DEEPSEEK_API_KEY}
+      - DEEPSEEK_BASE_URL
+      - DEEPSEEK_NO_COLOR
+    volumes:
+      - codewhale-home:/home/codewhale/.deepseek
+      - ${CODEWHALE_WORKSPACE:?set CODEWHALE_WORKSPACE to the project directory}:/workspace
+      # Mount SSH material only for projects that need it, and prefer read-only.
+      # - ${HOME}/.ssh:/home/codewhale/.ssh:ro
+      # Mount local CA certificates only when starting through a command that
+      # runs `sudo update-ca-certificates` inside this toolbox image.
+      # - ${CODEWHALE_CERTS_DIR:-../../docker/certs}:/usr/local/share/ca-certificates/local:ro
+    working_dir: /workspace
+    stdin_open: true
+    tty: true
+
+volumes:
+  codewhale-home:
+    name: ${CODEWHALE_HOME_VOLUME:-codewhale-toolbox-home}
diff --git a/docs/rfcs/2189-persistence-sqlite.md b/docs/rfcs/2189-persistence-sqlite.md
new file mode 100644
index 00000000..0396a546
--- /dev/null
+++ b/docs/rfcs/2189-persistence-sqlite.md
@@ -0,0 +1,86 @@
+# RFC: Persistence SQLite Migration
+...
+
+### 1.1 `crates/state` — partial SQLite (rusqlite)
+
+**Backend**: SQLite via `rusqlite` (not sqlx).  
+**Path**: `~/.deepseek/state.db`  
+**Tables**: `threads`, `thread_dynamic_tools`, `messages`, `checkpoints`, `jobs`  
+**Also**: `session_index.jsonl` — append-only JSONL for thread-name lookups.  
+**Schema versioning**: none — table shape is versioned implicitly by the binary.
+
+### 1.2 `crates/tui/src/session_manager.rs` — JSON sessions
+
+**Backend**: individual JSON files + atomic writes via `write_atomic`.  
+**Paths**:
+- `~/.codewhale/sessions/{id}.json` (preferred, v0.8.44+) or `~/.deepseek/sessions/{id}.json` (fallback)
+- `~/.deepseek/sessions/checkpoints/latest.json` — crash-recovery checkpoint
+- `~/.deepseek/sessions/checkpoints/offline_queue.json` — offline/degraded-mode queue
+
+**Schema constants**:
+- `CURRENT_SESSION_SCHEMA_VERSION: u32 = 1` (`SavedSession`)
+- `CURRENT_QUEUE_SCHEMA_VERSION: u32 = 1` (`OfflineQueueState`)
+
+**Policy**: reject-newer — older binary will refuse to load data written by a newer version.
+
+### 1.3 `crates/tui/src/runtime_threads.rs` — JSON runtime store
+
+**Backend**: per-record JSON files + append-only JSONL for events.  
+**Paths** (under `~/.deepseek/tasks/runtime/` or `DEEPSEEK_RUNTIME_DIR`):
+- `threads/{id}.json`
+- `turns/{id}.json`
+- `items/{id}.json`
+- `events/{thread_id}.jsonl` — append-only JSONL event timeline
+- `state.json` — global monotonic sequence counter
+
+**Schema constants**:
+- `CURRENT_RUNTIME_SCHEMA_VERSION: u32 = 2`
+
+**Policy**: reject-newer.
+
+### 1.4 `crates/tui/src/task_manager.rs` — JSON task store
+
+**Backend**: per-record JSON files + atomic writes.  
+**Paths** (under `~/.deepseek/tasks/` or `DEEPSEEK_TASKS_DIR`):
+- `{id}.json` — per-task records
+- `queue.json` — queue state
+
+**Schema constants**:
+- `CURRENT_TASK_SCHEMA_VERSION: u32 = 2`
+
+**Policy**: reject-newer.
+
+### 1.5 `crates/tui/src/automation_manager.rs` — JSON automation store
+
+**Backend**: per-record JSON files.  
+**Paths** (under `~/.deepseek/automations/` or `DEEPSEEK_AUTOMATIONS_DIR`):
+- `{id}.json`
+
+**Schema constants**:
+- `CURRENT_AUTOMATION_SCHEMA_VERSION: u32 = 1`
+
+### 1.6 `crates/tui/src/audit.rs` — JSONL audit log
+
+**Backend**: append-only JSONL with fsync after each event.  
+**Path**: `~/.deepseek/audit.log`  
+**Schema**: no version field — each line is a `{"ts", "event", "details"}` blob.
+
+### 1.7 Summary of issues
+
+| Area | Backend | Schema Version | Write Strategy | Queryability |
+|------|---------|---------------|----------------|-------------|
+| state (threads/messages/jobs) | SQLite | implicit | direct SQL | SQL |
+| sessions | JSON files | v1 | atomic rename | file scan |
+| runtime threads/turns/items | JSON files | v2 | atomic rename | file scan |
+| runtime events | JSONL | v2 | append+fsync | linear scan |
+| tasks | JSON files | v2 | atomic rename | file scan |
+| automations | JSON files | v1 | atomic rename | file scan |
+| audit | JSONL | none | append+fsync | linear scan |
+
+**Key pain points**:
+1. **Listing** threads/sessions/tasks requires scanning directories and deserializing every file.
+2. **Filtering** (e.g., "all failed tasks in last 7 days") requires full scans.
+3. **No transactional consistency** — a crash between saving a turn and its items can leave orphans.
+4. **Event timeline growth** — JSONL append is O(n) for replay; no indexing.
+5. **Six different schema version constants** across four modules, each with the same reject-newer policy.
+
diff --git a/docs/rfcs/2190-mcp-modularization.md b/docs/rfcs/2190-mcp-modularization.md
new file mode 100644
index 00000000..26f86420
--- /dev/null
+++ b/docs/rfcs/2190-mcp-modularization.md
@@ -0,0 +1,226 @@
+# RFC: MCP Modularization
+
+**Issue:** #2190
+**Status:** Draft
+**Date:** 2026-05-26
+
+## 1. Current state
+
+### 1.1 `codewhale-mcp` crate (`crates/mcp/`)
+
+The current MCP implementation lives in a single crate with two responsibilities:
+
+- **MCP client** — connects to MCP servers over stdio, manages protocol handshake,
+  tool discovery, and tool invocation. Used by the TUI to surface MCP tools as
+  `mcp_<server>_<tool>` entries in the tool registry.
+- **MCP stdio server** — a minimal MCP server that exposes CodeWhale's own tools
+  over stdio for external MCP clients. Used by the `codewhale mcp` CLI subcommand.
+
+Both the client and server share protocol types (JSON-RPC messages, tool schemas)
+but have different lifecycle concerns and different callers.
+
+### 1.2 Integration points
+
+- `crates/tui/src/mcp.rs` — MCP client integration: server lifecycle, tool
+  discovery, tool execution forwarding
+- `crates/tui/src/mcp_server.rs` — MCP stdio server: exposes TUI tools via
+  stdio MCP protocol
+- `docs/MCP.md` — user-facing documentation
+
+## 2. Motivation
+
+### 2.1 Separation of concerns
+
+The client and server share a crate but have no shared code paths at runtime.
+They import the same protocol types but serve different roles:
+- The client is **outbound** — it connects to external servers
+- The server is **inbound** — it accepts connections from external clients
+
+Mixing them in one crate creates unnecessary coupling: changes to the server
+API recompile the client, and vice versa.
+
+### 2.2 OAuth support
+
+The current MCP client has no OAuth support. MCP servers that require OAuth
+(e.g., GitHub, Google) cannot be used. Adding OAuth to the client requires:
+- Token storage (keychain, env-based, or config-based)
+- OAuth flow (device code, PKCE, or client credentials)
+- Token refresh and expiry handling
+
+These concerns are client-side only and should not affect the server crate.
+
+### 2.3 Reuse outside the TUI
+
+The MCP client is currently embedded in the TUI binary. If we want to use
+MCP tools from:
+- The `app-server` (HTTP/SSE runtime API)
+- The `codewhale` CLI (non-interactive mode)
+- External consumers (library use)
+
+...the client needs to be a standalone crate with a clean public API.
+
+## 3. Proposed crate split
+
+```
+crates/mcp/           →  crates/mcp-protocol/   (shared types, no I/O)
+                          crates/mcp-client/     (client implementation)
+                          crates/mcp-server/     (server implementation)
+```
+
+### 3.1 `codewhale-mcp-protocol`
+
+**Contents:** JSON-RPC message types, tool schema types, protocol constants,
+handshake types, error types. No I/O, no async runtime dependency.
+
+**Dependencies:** `serde`, `serde_json`, `codewhale-protocol` (for tool schema)
+
+**Public API:**
+```rust
+pub mod messages;     // JSON-RPC request/response/notification types
+pub mod tools;        // MCP tool schema types
+pub mod errors;       // MCP error codes
+pub mod version;      // Protocol version constants
+```
+
+### 3.2 `codewhale-mcp-client`
+
+**Contents:** MCP client: stdio transport, process management, handshake,
+tool discovery, tool invocation, OAuth support.
+
+**Dependencies:** `codewhale-mcp-protocol`, `tokio`, `serde_json`, `tracing`,
+`oauth2` (new, for OAuth), `keyring` (optional, for token storage)
+
+**Public API:**
+```rust
+pub struct McpClient {
+    // Configuration
+}
+
+impl McpClient {
+    pub async fn connect(config: McpClientConfig) -> Result<Self>;
+    pub async fn list_tools(&self) -> Result<Vec<ToolSchema>>;
+    pub async fn call_tool(&self, name: &str, args: Value) -> Result<Value>;
+    pub async fn disconnect(self);
+}
+
+pub struct McpClientConfig {
+    pub command: String,           // e.g., "npx", "python"
+    pub args: Vec<String>,         // e.g., ["-y", "@modelcontextprotocol/server-github"]
+    pub env: HashMap<String, String>,
+    pub oauth: Option<OAuthConfig>,
+    pub timeout: Duration,
+}
+
+pub struct OAuthConfig {
+    pub provider: OAuthProvider,
+    pub client_id: String,
+    pub scopes: Vec<String>,
+    pub token_storage: TokenStorage,
+}
+
+pub enum OAuthProvider {
+    Github,
+    Google,
+    Custom { auth_url: String, token_url: String },
+}
+```
+
+### 3.3 `codewhale-mcp-server`
+
+**Contents:** MCP stdio server: accepts connections, exposes tool list,
+handles tool calls, manages stdio transport.
+
+**Dependencies:** `codewhale-mcp-protocol`, `codewhale-tools`, `tokio`,
+`serde_json`, `tracing`
+
+**Public API:**
+```rust
+pub struct McpServer {
+    // Tool registry
+}
+
+impl McpServer {
+    pub fn new(tools: Vec<Arc<dyn ToolSpec>>) -> Self;
+    pub async fn serve_stdio(self) -> Result<()>;
+    pub async fn serve_sse(self, addr: SocketAddr) -> Result<()>;
+}
+```
+
+## 4. Migration path
+
+### Phase 1: Extract protocol crate (non-breaking)
+
+1. Move shared types from `crates/mcp/src/` to `crates/mcp-protocol/src/`
+2. Re-export from `codewhale-mcp` for backward compatibility
+3. Update `Cargo.toml` in `codewhale-mcp` to depend on `codewhale-mcp-protocol`
+
+### Phase 2: Split client and server (breaking for direct imports)
+
+1. Create `crates/mcp-client/` with client code
+2. Create `crates/mcp-server/` with server code
+3. Update `codewhale-tui` to depend on `codewhale-mcp-client`
+4. Update `codewhale-cli` to depend on `codewhale-mcp-server`
+5. Deprecate `codewhale-mcp` crate (re-exports from new crates)
+
+### Phase 3: Remove legacy crate
+
+1. Remove `crates/mcp/` after a deprecation cycle (one release)
+
+## 5. OAuth integration
+
+### 5.1 Token storage
+
+Tokens should be stored securely. Options (in priority order):
+1. OS keychain via `keyring` crate (macOS Keychain, Windows Credential Manager,
+   Linux Secret Service)
+2. Encrypted file in `~/.codewhale/mcp-credentials/` (fallback)
+3. Environment variable `MCP_OAUTH_TOKEN_<PROVIDER>`
+
+### 5.2 OAuth flows
+
+Initial implementation supports:
+- **Device Code Flow** (GitHub) — user opens a URL, enters a code
+- **Client Credentials** — for service-to-service MCP servers
+
+Future (deferred):
+- **PKCE** — for user-facing OAuth with redirect
+- **Token refresh** — automatic refresh with refresh_token
+
+### 5.3 Configuration
+
+```toml
+# ~/.codewhale/config.toml
+[mcp.servers.github]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-github"]
+
+[mcp.servers.github.oauth]
+provider = "github"
+client_id = "your-client-id"
+scopes = ["repo", "read:org"]
+```
+
+## 6. Risks and unknowns
+
+| Risk | Mitigation |
+|---|---|
+| Crate proliferation | 3 small crates vs 1 medium crate; each has a clear purpose |
+| Breaking internal imports | Phase 2 carries `codewhale-mcp` deprecation shim for one release |
+| OAuth token security | OS keychain preferred; encrypted fallback with file permissions |
+| Testing complexity | Each crate has its own test suite; integration tests remain in `crates/tui/tests/` |
+| Dependency bloat | `oauth2` and `keyring` are optional features; consumers opt in |
+
+## 7. Out of scope (future RFCs)
+
+- MCP over HTTP/SSE transport (currently stdio only)
+- MCP server discovery (currently explicit config)
+- MCP tool result streaming (currently request-response)
+- MCP server-side tool approval flows
+
+## Related
+
+- `crates/mcp/src/` — current implementation
+- `crates/tui/src/mcp.rs` — TUI MCP integration
+- `crates/tui/src/mcp_server.rs` — MCP stdio server
+- `docs/MCP.md` — user-facing documentation
+- Issue #2190 — this RFC
diff --git a/integrations/feishu-bridge/package-lock.json b/integrations/feishu-bridge/package-lock.json
index 9b00cd14..59a9402b 100644
--- a/integrations/feishu-bridge/package-lock.json
+++ b/integrations/feishu-bridge/package-lock.json
@@ -510,9 +510,9 @@
       }
     },
     "node_modules/qs": {
-      "version": "6.15.1",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz",
-      "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==",
+      "version": "6.15.2",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz",
+      "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==",
       "license": "BSD-3-Clause",
       "dependencies": {
         "side-channel": "^1.1.0"
diff --git a/integrations/feishu-bridge/package.json b/integrations/feishu-bridge/package.json
index 9ee1fcc6..f67c33a7 100644
--- a/integrations/feishu-bridge/package.json
+++ b/integrations/feishu-bridge/package.json
@@ -15,7 +15,8 @@
     "@larksuiteoapi/node-sdk": "^1.52.0"
   },
   "overrides": {
-    "axios": "^1.16.1"
+    "axios": "^1.16.1",
+    "qs": ">=6.15.2"
   },
   "engines": {
     "node": ">=18"
diff --git a/npm/codewhale/package.json b/npm/codewhale/package.json
index 3f6c3cb2..5413ba70 100644
--- a/npm/codewhale/package.json
+++ b/npm/codewhale/package.json
@@ -1,7 +1,7 @@
 {
   "name": "codewhale",
-  "version": "0.8.44",
-  "codewhaleBinaryVersion": "0.8.44",
+  "version": "0.8.46",
+  "codewhaleBinaryVersion": "0.8.46",
   "description": "Install and run CodeWhale, the agentic terminal for open-source and open-weight coding models, from GitHub release artifacts.",
   "author": "Hmbown",
   "license": "MIT",
diff --git a/npm/codewhale/scripts/artifacts.js b/npm/codewhale/scripts/artifacts.js
index 27117b0c..c0a74f4f 100644
--- a/npm/codewhale/scripts/artifacts.js
+++ b/npm/codewhale/scripts/artifacts.js
@@ -7,6 +7,7 @@ const ASSET_MATRIX = {
   linux: {
     x64: ["codewhale-linux-x64", "codewhale-tui-linux-x64"],
     arm64: ["codewhale-linux-arm64", "codewhale-tui-linux-arm64"],
+    riscv64: ["codewhale-linux-riscv64", "codewhale-tui-linux-riscv64"],
   },
   darwin: {
     x64: ["codewhale-macos-x64", "codewhale-tui-macos-x64"],
@@ -78,12 +79,21 @@ function executableName(base, platform) {
 }
 
 function releaseBaseUrl(version, repo = "Hmbown/CodeWhale") {
+  // CODEWHALE_RELEASE_BASE_URL is the canonical override.
+  // DEEPSEEK_TUI_RELEASE_BASE_URL / DEEPSEEK_RELEASE_BASE_URL are legacy aliases.
   const override =
-    process.env.DEEPSEEK_TUI_RELEASE_BASE_URL || process.env.DEEPSEEK_RELEASE_BASE_URL;
+    process.env.CODEWHALE_RELEASE_BASE_URL ||
+    process.env.DEEPSEEK_TUI_RELEASE_BASE_URL ||
+    process.env.DEEPSEEK_RELEASE_BASE_URL;
   if (override) {
     const trimmed = String(override).trim();
     return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
   }
+  // When CODEWHALE_USE_CNB_MIRROR is set, use the CNB (China-friendly)
+  // mirror that already builds and publishes binary release assets.
+  if (process.env.CODEWHALE_USE_CNB_MIRROR) {
+    return `https://cnb.cool/Hmbown/CodeWhale/-/releases/v${version}/`;
+  }
   return `https://github.com/${repo}/releases/download/v${version}/`;
 }
 
diff --git a/npm/codewhale/test/artifacts.test.js b/npm/codewhale/test/artifacts.test.js
index 1fd74955..e16e88fd 100644
--- a/npm/codewhale/test/artifacts.test.js
+++ b/npm/codewhale/test/artifacts.test.js
@@ -55,6 +55,7 @@ test("known platforms are unaffected by alias map", () => {
   for (const [platform, arch, expectedCodeWhale] of [
     ["linux", "x64", "codewhale-linux-x64"],
     ["darwin", "arm64", "codewhale-macos-arm64"],
+    ["linux", "riscv64", "codewhale-linux-riscv64"],
     ["win32", "x64", "codewhale-windows-x64.exe"],
   ]) {
     withMockedOs(platform, arch, () => {
diff --git a/npm/deepseek-tui/package.json b/npm/deepseek-tui/package.json
index bbca3bb6..75462031 100644
--- a/npm/deepseek-tui/package.json
+++ b/npm/deepseek-tui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "deepseek-tui",
-  "version": "0.8.44",
+  "version": "0.8.46",
   "description": "Legacy compatibility package. Renamed to `codewhale`; run `npm install -g codewhale` for new installs.",
   "author": "Hmbown",
   "license": "MIT",
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 00000000..cbfc7a7e
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,1610 @@
+{
+  "name": "codewhale",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "devDependencies": {
+        "wrangler": "^4.94.0"
+      }
+    },
+    "node_modules/@cloudflare/kv-asset-handler": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/@cloudflare/kv-asset-handler/-/kv-asset-handler-0.5.0.tgz",
+      "integrity": "sha512-jxQYkj8dSIzc0cD6cMMNdOc1UVjqSqu8BZdor5s8cGjW2I8BjODt/kWPVdY+u9zj3ms75Q5qaZgnxUad83+eAg==",
+      "dev": true,
+      "license": "MIT OR Apache-2.0",
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/@cloudflare/unenv-preset": {
+      "version": "2.16.1",
+      "resolved": "https://registry.npmjs.org/@cloudflare/unenv-preset/-/unenv-preset-2.16.1.tgz",
+      "integrity": "sha512-ECxObrMfyTl5bhQf/lZCXwo5G6xX9IAUo+nDMKK4SZ8m4Jvvxp52vilxyySSWh2YTZz8+HQ07qGH/2rEom1vDw==",
+      "dev": true,
+      "license": "MIT OR Apache-2.0",
+      "peerDependencies": {
+        "unenv": "2.0.0-rc.24",
+        "workerd": ">1.20260305.0 <2.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "workerd": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@cloudflare/workerd-darwin-64": {
+      "version": "1.20260521.1",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260521.1.tgz",
+      "integrity": "sha512-aiNdXmxlhwGjTSajL3I7uQPpN4lAOcXjvg5ZOlJKIywnevr798n9XCS6lvuqgniM3KjurBNWRRypMJntg/eSLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-darwin-arm64": {
+      "version": "1.20260521.1",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260521.1.tgz",
+      "integrity": "sha512-ikN8aKSi4Ak28ndOkuSO5rq6lmV6wwDQu9F9Vu6J7EkwAOth74J/Hjn4j4EuFceW/npw2Ws0Y/muzA6WKHl4TA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-linux-64": {
+      "version": "1.20260521.1",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260521.1.tgz",
+      "integrity": "sha512-D/gUhvQcG0pJr5aJl6yUoi2JxbFpjVtDq9xUJHPjfkAjL28TUVgCR/e5r8YGirepv4I1DK7ihuii9LZ2GGMJbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-linux-arm64": {
+      "version": "1.20260521.1",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260521.1.tgz",
+      "integrity": "sha512-vhjWPIHenczegTakhRPwEmTeaavCpNqsuo3RlLCkUdU47HrwLvy/4QersGggs4+kF4Do+IE/EznCGyT40xYcLA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cloudflare/workerd-windows-64": {
+      "version": "1.20260521.1",
+      "resolved": "https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260521.1.tgz",
+      "integrity": "sha512-wBolYC/+lnGIEbkkPdzFtjTOWip2uQH6maeAP1ZV0kyxi5SGpsa83+wD5rH5OOle+sHE5qJMdwCKjwRwj+FKJg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/@cspotcode/source-map-support": {
+      "version": "0.8.1",
+      "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
+      "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "0.3.9"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+      "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.3.tgz",
+      "integrity": "sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.3.tgz",
+      "integrity": "sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.3.tgz",
+      "integrity": "sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.3.tgz",
+      "integrity": "sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.3.tgz",
+      "integrity": "sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.3.tgz",
+      "integrity": "sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.3.tgz",
+      "integrity": "sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.3.tgz",
+      "integrity": "sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.3.tgz",
+      "integrity": "sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.3.tgz",
+      "integrity": "sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.3.tgz",
+      "integrity": "sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.3.tgz",
+      "integrity": "sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.3.tgz",
+      "integrity": "sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.3.tgz",
+      "integrity": "sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.3.tgz",
+      "integrity": "sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.3.tgz",
+      "integrity": "sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.3.tgz",
+      "integrity": "sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.3.tgz",
+      "integrity": "sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.3.tgz",
+      "integrity": "sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.3.tgz",
+      "integrity": "sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.3.tgz",
+      "integrity": "sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.3.tgz",
+      "integrity": "sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.3.tgz",
+      "integrity": "sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.3.tgz",
+      "integrity": "sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@img/colour": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz",
+      "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@img/sharp-darwin-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz",
+      "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-darwin-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
+      "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz",
+      "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
+      "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
+      "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
+      "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-ppc64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz",
+      "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-riscv64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz",
+      "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-s390x": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz",
+      "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
+      "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
+      "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
+      "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
+      "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
+      "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-ppc64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz",
+      "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-ppc64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-riscv64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz",
+      "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-riscv64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-s390x": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz",
+      "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-s390x": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
+      "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
+      "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
+      "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-wasm32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz",
+      "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==",
+      "cpu": [
+        "wasm32"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/runtime": "^1.7.0"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
+      "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-ia32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz",
+      "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
+      "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.9",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
+      "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.0.3",
+        "@jridgewell/sourcemap-codec": "^1.4.10"
+      }
+    },
+    "node_modules/@poppinss/colors": {
+      "version": "4.1.6",
+      "resolved": "https://registry.npmjs.org/@poppinss/colors/-/colors-4.1.6.tgz",
+      "integrity": "sha512-H9xkIdFswbS8n1d6vmRd8+c10t2Qe+rZITbbDHHkQixH5+2x1FDGmi/0K+WgWiqQFKPSlIYB7jlH6Kpfn6Fleg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "kleur": "^4.1.5"
+      }
+    },
+    "node_modules/@poppinss/dumper": {
+      "version": "0.6.5",
+      "resolved": "https://registry.npmjs.org/@poppinss/dumper/-/dumper-0.6.5.tgz",
+      "integrity": "sha512-NBdYIb90J7LfOI32dOewKI1r7wnkiH6m920puQ3qHUeZkxNkQiFnXVWoE6YtFSv6QOiPPf7ys6i+HWWecDz7sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@poppinss/colors": "^4.1.5",
+        "@sindresorhus/is": "^7.0.2",
+        "supports-color": "^10.0.0"
+      }
+    },
+    "node_modules/@poppinss/exception": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@poppinss/exception/-/exception-1.2.3.tgz",
+      "integrity": "sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@sindresorhus/is": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.2.0.tgz",
+      "integrity": "sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sindresorhus/is?sponsor=1"
+      }
+    },
+    "node_modules/@speed-highlight/core": {
+      "version": "1.2.15",
+      "resolved": "https://registry.npmjs.org/@speed-highlight/core/-/core-1.2.15.tgz",
+      "integrity": "sha512-BMq1K3DsElxDWawkX6eLg9+CKJrTVGCBAWVuHXVUV2u0s2711qiChLSId6ikYPfxhdYocLNt3wWwSvDiTvFabw==",
+      "dev": true,
+      "license": "CC0-1.0"
+    },
+    "node_modules/blake3-wasm": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/blake3-wasm/-/blake3-wasm-2.1.5.tgz",
+      "integrity": "sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/cookie": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz",
+      "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/error-stack-parser-es": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/error-stack-parser-es/-/error-stack-parser-es-1.0.5.tgz",
+      "integrity": "sha512-5qucVt2XcuGMcEGgWI7i+yZpmpByQ8J1lHhcL7PwqCwu9FPP3VUXzT4ltHe5i2z9dePwEHcDVOAfSnHsOlCXRA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.27.3",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.3.tgz",
+      "integrity": "sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.3",
+        "@esbuild/android-arm": "0.27.3",
+        "@esbuild/android-arm64": "0.27.3",
+        "@esbuild/android-x64": "0.27.3",
+        "@esbuild/darwin-arm64": "0.27.3",
+        "@esbuild/darwin-x64": "0.27.3",
+        "@esbuild/freebsd-arm64": "0.27.3",
+        "@esbuild/freebsd-x64": "0.27.3",
+        "@esbuild/linux-arm": "0.27.3",
+        "@esbuild/linux-arm64": "0.27.3",
+        "@esbuild/linux-ia32": "0.27.3",
+        "@esbuild/linux-loong64": "0.27.3",
+        "@esbuild/linux-mips64el": "0.27.3",
+        "@esbuild/linux-ppc64": "0.27.3",
+        "@esbuild/linux-riscv64": "0.27.3",
+        "@esbuild/linux-s390x": "0.27.3",
+        "@esbuild/linux-x64": "0.27.3",
+        "@esbuild/netbsd-arm64": "0.27.3",
+        "@esbuild/netbsd-x64": "0.27.3",
+        "@esbuild/openbsd-arm64": "0.27.3",
+        "@esbuild/openbsd-x64": "0.27.3",
+        "@esbuild/openharmony-arm64": "0.27.3",
+        "@esbuild/sunos-x64": "0.27.3",
+        "@esbuild/win32-arm64": "0.27.3",
+        "@esbuild/win32-ia32": "0.27.3",
+        "@esbuild/win32-x64": "0.27.3"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/kleur": {
+      "version": "4.1.5",
+      "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz",
+      "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/miniflare": {
+      "version": "4.20260521.0",
+      "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-4.20260521.0.tgz",
+      "integrity": "sha512-roRfxPq49OkuSeQsc43hRjSB1+HdHtDNKRwDEVk2hCjCBuBWxb5Wvwq88b0ULj6QVEJLN/+ZqF19M+h4VYJ/zg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@cspotcode/source-map-support": "0.8.1",
+        "sharp": "^0.34.5",
+        "undici": "7.24.8",
+        "workerd": "1.20260521.1",
+        "ws": "8.20.1",
+        "youch": "4.1.0-beta.10"
+      },
+      "bin": {
+        "miniflare": "bootstrap.js"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      }
+    },
+    "node_modules/path-to-regexp": {
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-6.3.0.tgz",
+      "integrity": "sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/rosie-skills": {
+      "version": "0.6.4",
+      "resolved": "https://registry.npmjs.org/rosie-skills/-/rosie-skills-0.6.4.tgz",
+      "integrity": "sha512-ojfhSiQRdZ2QyWbmKAHOSAUbaLYrTc5zIH7mS1jKoP8KCFSQddwVhMyFqldckTeybTfW3zNcsZzyOTzGTN1SBA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "bin": {
+        "rosie-skills": "dist/bin.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "rosie-skills-darwin-arm64": "0.6.4",
+        "rosie-skills-freebsd-x64": "0.6.4",
+        "rosie-skills-linux-x64": "0.6.4"
+      }
+    },
+    "node_modules/rosie-skills-darwin-arm64": {
+      "version": "0.6.4",
+      "resolved": "https://registry.npmjs.org/rosie-skills-darwin-arm64/-/rosie-skills-darwin-arm64-0.6.4.tgz",
+      "integrity": "sha512-rn1s5hqFKcxeiDEWWoFa1hdGPshR8TkwHLzy/cBavb9XJNAaUxbe3oQ78W9sQkRHAgRyzJYyk9tw68Qrdnizgg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/rosie-skills-freebsd-x64": {
+      "version": "0.6.4",
+      "resolved": "https://registry.npmjs.org/rosie-skills-freebsd-x64/-/rosie-skills-freebsd-x64-0.6.4.tgz",
+      "integrity": "sha512-SxCRduPBMtfjkQ+q56Yw9OLA3PyaqoALzt7kER7IDKuUVfM2O/1w8sa5xhTDiCvWkZJixnH5d5Ya6KT+/Mwcng==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/rosie-skills-linux-x64": {
+      "version": "0.6.4",
+      "resolved": "https://registry.npmjs.org/rosie-skills-linux-x64/-/rosie-skills-linux-x64-0.6.4.tgz",
+      "integrity": "sha512-D9Y9mfu7goB0s0X59uU3hcFeUTef3VbpCIDwFMzyvJrAq3XhRACWBDMHQsHlyWdHxTXPX/ILyW65RXyrJlgqng==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/semver": {
+      "version": "7.8.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.1.tgz",
+      "integrity": "sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/sharp": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
+      "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@img/colour": "^1.0.0",
+        "detect-libc": "^2.1.2",
+        "semver": "^7.7.3"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-darwin-arm64": "0.34.5",
+        "@img/sharp-darwin-x64": "0.34.5",
+        "@img/sharp-libvips-darwin-arm64": "1.2.4",
+        "@img/sharp-libvips-darwin-x64": "1.2.4",
+        "@img/sharp-libvips-linux-arm": "1.2.4",
+        "@img/sharp-libvips-linux-arm64": "1.2.4",
+        "@img/sharp-libvips-linux-ppc64": "1.2.4",
+        "@img/sharp-libvips-linux-riscv64": "1.2.4",
+        "@img/sharp-libvips-linux-s390x": "1.2.4",
+        "@img/sharp-libvips-linux-x64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4",
+        "@img/sharp-linux-arm": "0.34.5",
+        "@img/sharp-linux-arm64": "0.34.5",
+        "@img/sharp-linux-ppc64": "0.34.5",
+        "@img/sharp-linux-riscv64": "0.34.5",
+        "@img/sharp-linux-s390x": "0.34.5",
+        "@img/sharp-linux-x64": "0.34.5",
+        "@img/sharp-linuxmusl-arm64": "0.34.5",
+        "@img/sharp-linuxmusl-x64": "0.34.5",
+        "@img/sharp-wasm32": "0.34.5",
+        "@img/sharp-win32-arm64": "0.34.5",
+        "@img/sharp-win32-ia32": "0.34.5",
+        "@img/sharp-win32-x64": "0.34.5"
+      }
+    },
+    "node_modules/supports-color": {
+      "version": "10.2.2",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz",
+      "integrity": "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/supports-color?sponsor=1"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/undici": {
+      "version": "7.24.8",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.24.8.tgz",
+      "integrity": "sha512-6KQ/+QxK49Z/p3HO6E5ZCZWNnCasyZLa5ExaVYyvPxUwKtbCPMKELJOqh7EqOle0t9cH/7d2TaaTRRa6Nhs4YQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.18.1"
+      }
+    },
+    "node_modules/unenv": {
+      "version": "2.0.0-rc.24",
+      "resolved": "https://registry.npmjs.org/unenv/-/unenv-2.0.0-rc.24.tgz",
+      "integrity": "sha512-i7qRCmY42zmCwnYlh9H2SvLEypEFGye5iRmEMKjcGi7zk9UquigRjFtTLz0TYqr0ZGLZhaMHl/foy1bZR+Cwlw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "pathe": "^2.0.3"
+      }
+    },
+    "node_modules/workerd": {
+      "version": "1.20260521.1",
+      "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20260521.1.tgz",
+      "integrity": "sha512-HzIThcZ0ZVEuzVxpY2IYZ3yssSrTjtrWXAVfmOl5rVwyqcu7aeZXGMiwrEmi9MOcC3wjy+BNv+hFrMMY5OrjQQ==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "workerd": "bin/workerd"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "optionalDependencies": {
+        "@cloudflare/workerd-darwin-64": "1.20260521.1",
+        "@cloudflare/workerd-darwin-arm64": "1.20260521.1",
+        "@cloudflare/workerd-linux-64": "1.20260521.1",
+        "@cloudflare/workerd-linux-arm64": "1.20260521.1",
+        "@cloudflare/workerd-windows-64": "1.20260521.1"
+      }
+    },
+    "node_modules/wrangler": {
+      "version": "4.94.0",
+      "resolved": "https://registry.npmjs.org/wrangler/-/wrangler-4.94.0.tgz",
+      "integrity": "sha512-GsNw0DomGFfeXFtKVTwn2X69UKcCxcTB0CXykjsMineJIxOeyrw7LovlHQ/3JU8KJHH7repLB+kOHvfTBA/Eew==",
+      "dev": true,
+      "license": "MIT OR Apache-2.0",
+      "dependencies": {
+        "@cloudflare/kv-asset-handler": "0.5.0",
+        "@cloudflare/unenv-preset": "2.16.1",
+        "blake3-wasm": "2.1.5",
+        "esbuild": "0.27.3",
+        "miniflare": "4.20260521.0",
+        "path-to-regexp": "6.3.0",
+        "rosie-skills": "^0.6.3",
+        "unenv": "2.0.0-rc.24",
+        "workerd": "1.20260521.1"
+      },
+      "bin": {
+        "wrangler": "bin/wrangler.js",
+        "wrangler2": "bin/wrangler.js"
+      },
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.2"
+      },
+      "peerDependencies": {
+        "@cloudflare/workers-types": "^4.20260521.1"
+      },
+      "peerDependenciesMeta": {
+        "@cloudflare/workers-types": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ws": {
+      "version": "8.20.1",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.1.tgz",
+      "integrity": "sha512-It4dO0K5v//JtTXuPkfEOaI3uUN87iYPnqo/ZzqCoG3g8uhA66QUMs/SrM0YK7/NAu+r4LMh/9dq2A7k+rHs+w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/youch": {
+      "version": "4.1.0-beta.10",
+      "resolved": "https://registry.npmjs.org/youch/-/youch-4.1.0-beta.10.tgz",
+      "integrity": "sha512-rLfVLB4FgQneDr0dv1oddCVZmKjcJ6yX6mS4pU82Mq/Dt9a3cLZQ62pDBL4AUO+uVrCvtWz3ZFUL2HFAFJ/BXQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@poppinss/colors": "^4.1.5",
+        "@poppinss/dumper": "^0.6.4",
+        "@speed-highlight/core": "^1.2.7",
+        "cookie": "^1.0.2",
+        "youch-core": "^0.3.3"
+      }
+    },
+    "node_modules/youch-core": {
+      "version": "0.3.3",
+      "resolved": "https://registry.npmjs.org/youch-core/-/youch-core-0.3.3.tgz",
+      "integrity": "sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@poppinss/exception": "^1.2.2",
+        "error-stack-parser-es": "^1.0.5"
+      }
+    }
+  }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 00000000..48cd75c6
--- /dev/null
+++ b/package.json
@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "wrangler": "^4.94.0"
+  }
+}
diff --git a/scripts/check-provider-registry.py b/scripts/check-provider-registry.py
new file mode 100644
index 00000000..2b805067
--- /dev/null
+++ b/scripts/check-provider-registry.py
@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Check that docs/PROVIDERS.md tracks the shipped provider registry.
+
+This is intentionally lightweight. It does not try to generate prose; it checks
+the stable identifiers and default strings that are easy for docs to drift from:
+
+- canonical ProviderKind IDs
+- provider TOML tables
+- live TUI ApiProvider IDs
+- shipped-provider table rows
+- static ModelRegistry provider rows
+- default provider model/base URL constants
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+CONFIG_RS = ROOT / "crates" / "config" / "src" / "lib.rs"
+TUI_CONFIG_RS = ROOT / "crates" / "tui" / "src" / "config.rs"
+AGENT_RS = ROOT / "crates" / "agent" / "src" / "lib.rs"
+PROVIDERS_MD = ROOT / "docs" / "PROVIDERS.md"
+
+
+API_PROVIDER_ONLY_IDS = {"deepseek-cn"}
+
+
+def read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def require_index(source: str, needle: str, context: str, start: int = 0) -> int:
+    try:
+        return source.index(needle, start)
+    except ValueError:
+        raise ValueError(f"{context}: missing {needle!r}") from None
+
+
+def markdown_section(source: str, heading: str) -> str:
+    start = require_index(source, heading, "docs/PROVIDERS.md")
+    next_heading = source.find("\n## ", start + len(heading))
+    end = len(source) if next_heading == -1 else next_heading
+    return source[start:end]
+
+
+def extract_match_block(
+    source: str, signature: str, context: str, start: int = 0
+) -> str:
+    start = require_index(source, signature, context, start)
+    match_start = require_index(source, "match", f"match block after {signature!r}", start)
+    brace_start = require_index(source, "{", f"match block after {signature!r}", match_start)
+    depth = 0
+    for index in range(brace_start, len(source)):
+        char = source[index]
+        if char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return source[brace_start + 1 : index]
+    raise ValueError(f"could not parse match block after {signature!r}")
+
+
+def provider_kind_ids(config_rs: str) -> dict[str, str]:
+    impl_start = require_index(
+        config_rs, "impl ProviderKind", "crates/config/src/lib.rs"
+    )
+    block = extract_match_block(
+        config_rs,
+        "pub fn as_str(self) -> &'static str",
+        "crates/config/src/lib.rs",
+        impl_start,
+    )
+    pairs = re.findall(r"Self::(\w+)\s*=>\s*\"([^\"]+)\"", block)
+    if not pairs:
+        raise ValueError("ProviderKind::as_str returned no providers")
+    return {variant: provider_id for variant, provider_id in pairs}
+
+
+def api_provider_ids(tui_config_rs: str) -> dict[str, str]:
+    impl_start = require_index(
+        tui_config_rs, "impl ApiProvider", "crates/tui/src/config.rs"
+    )
+    block = extract_match_block(
+        tui_config_rs,
+        "pub fn as_str(self) -> &'static str",
+        "crates/tui/src/config.rs",
+        impl_start,
+    )
+    pairs = re.findall(r"Self::(\w+)\s*=>\s*\"([^\"]+)\"", block)
+    if not pairs:
+        raise ValueError("ApiProvider::as_str returned no providers")
+    return {variant: provider_id for variant, provider_id in pairs}
+
+
+def provider_tables(config_rs: str) -> set[str]:
+    struct_start = require_index(
+        config_rs, "pub struct ProvidersToml", "crates/config/src/lib.rs"
+    )
+    struct_end = require_index(config_rs, "\n}", "ProvidersToml struct", struct_start)
+    fields = re.findall(
+        r"pub\s+([a-z0-9_]+)\s*:\s*ProviderConfigToml",
+        config_rs[struct_start:struct_end],
+    )
+    if not fields:
+        raise ValueError("ProvidersToml returned no provider tables")
+    return set(fields)
+
+
+def shipped_provider_rows(providers_md: str) -> set[str]:
+    table = markdown_section(providers_md, "## Shipped Providers")
+    return set(re.findall(r"^\|\s*`([^`]+)`\s*\|", table, flags=re.MULTILINE))
+
+
+def shipped_provider_tables(providers_md: str) -> set[str]:
+    table = markdown_section(providers_md, "## Shipped Providers")
+    return set(re.findall(r"\|\s*`\[providers\.([a-z0-9_]+)\]`\s*\|", table))
+
+
+def static_registry_provider_rows(providers_md: str) -> set[str]:
+    table = markdown_section(providers_md, "## Static Model Registry")
+    return set(re.findall(r"^\|\s*`([^`]+)`\s*\|", table, flags=re.MULTILINE))
+
+
+def model_registry_providers(agent_rs: str, variant_to_id: dict[str, str]) -> set[str]:
+    variants = set(re.findall(r"provider:\s*ProviderKind::(\w+)", agent_rs))
+    missing = variants - set(variant_to_id)
+    if missing:
+        raise ValueError(f"ModelRegistry uses unknown provider variants: {sorted(missing)}")
+    return {variant_to_id[variant] for variant in variants}
+
+
+def default_strings(tui_config_rs: str) -> set[str]:
+    defaults = set()
+    for name, value in re.findall(
+        r'const\s+(DEFAULT_[A-Z0-9_]+(?:MODEL|BASE_URL)):\s*&str\s*=\s*"([^"]+)"',
+        tui_config_rs,
+    ):
+        if name == "DEFAULT_DEEPSEEKCN_BASE_URL":
+            continue
+        defaults.add(value)
+    if not defaults:
+        raise ValueError("no default provider model/base URL constants found")
+    return defaults
+
+
+def missing_default_strings(providers_md: str, defaults: set[str]) -> list[str]:
+    # Inline-code validation should not let fenced TOML/bash examples pair a
+    # stray backtick with later prose; strip fenced blocks before scanning.
+    inline_source = re.sub(r"```.*?```", "", providers_md, flags=re.DOTALL)
+    code_spans = set(re.findall(r"`([^`]+)`", inline_source))
+    return sorted(defaults - code_spans)
+
+
+def report_set(label: str, expected: set[str], actual: set[str]) -> list[str]:
+    errors = []
+    missing = sorted(expected - actual)
+    extra = sorted(actual - expected)
+    if missing:
+        errors.append(f"{label} missing: {', '.join(missing)}")
+    if extra:
+        errors.append(f"{label} extra: {', '.join(extra)}")
+    return errors
+
+
+def report_provider_enum_drift(
+    provider_kind_ids: set[str], api_provider_ids: set[str]
+) -> list[str]:
+    errors = []
+    missing_from_api_provider = sorted(provider_kind_ids - api_provider_ids)
+    unexpected_api_provider_ids = sorted(
+        api_provider_ids - provider_kind_ids - API_PROVIDER_ONLY_IDS
+    )
+    missing_allowlisted_ids = sorted(API_PROVIDER_ONLY_IDS - api_provider_ids)
+
+    if missing_from_api_provider:
+        errors.append(
+            "ApiProvider missing ProviderKind IDs: "
+            + ", ".join(missing_from_api_provider)
+        )
+    if unexpected_api_provider_ids:
+        errors.append(
+            "ApiProvider has non-whitelisted IDs absent from ProviderKind: "
+            + ", ".join(unexpected_api_provider_ids)
+        )
+    if missing_allowlisted_ids:
+        errors.append(
+            "ApiProvider-only whitelist entries are absent from ApiProvider: "
+            + ", ".join(missing_allowlisted_ids)
+        )
+    return errors
+
+
+def main() -> int:
+    try:
+        config_rs = read(CONFIG_RS)
+        tui_config_rs = read(TUI_CONFIG_RS)
+        agent_rs = read(AGENT_RS)
+        providers_md = read(PROVIDERS_MD)
+
+        variant_to_id = provider_kind_ids(config_rs)
+        canonical_ids = set(variant_to_id.values())
+        live_api_provider_ids = set(api_provider_ids(tui_config_rs).values())
+        expected_tables = {provider_id.replace("-", "_") for provider_id in canonical_ids}
+
+        errors: list[str] = []
+        errors += report_provider_enum_drift(canonical_ids, live_api_provider_ids)
+        errors += report_set(
+            "shipped provider rows",
+            canonical_ids,
+            shipped_provider_rows(providers_md),
+        )
+        errors += report_set("provider TOML tables", expected_tables, provider_tables(config_rs))
+        errors += report_set(
+            "documented provider TOML tables",
+            expected_tables,
+            shipped_provider_tables(providers_md),
+        )
+        errors += report_set(
+            "static ModelRegistry rows",
+            model_registry_providers(agent_rs, variant_to_id),
+            static_registry_provider_rows(providers_md),
+        )
+
+        missing_defaults = missing_default_strings(providers_md, default_strings(tui_config_rs))
+        if missing_defaults:
+            errors.append(
+                "docs/PROVIDERS.md does not mention default strings as Markdown code spans: "
+                + ", ".join(missing_defaults)
+            )
+    except ValueError as err:
+        errors = [str(err)]
+
+    if errors:
+        print("Provider registry drift check failed:", file=sys.stderr)
+        for error in errors:
+            print(f"- {error}", file=sys.stderr)
+        return 1
+
+    print("Provider registry drift check passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/measure-tool-catalog.py b/scripts/measure-tool-catalog.py
new file mode 100755
index 00000000..c5b40367
--- /dev/null
+++ b/scripts/measure-tool-catalog.py
@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Measure serialized tool catalog size before and after default deferral.
+
+This delegates catalog construction to an ignored Rust test so the measurement
+uses the same tool definitions, JSON serialization, and deferral policy as the
+runtime. Token counts are deterministic estimates using ceil(serialized_bytes/4).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+
+MARKER = "TOOL_CATALOG_METRICS "
+
+
+def main() -> int:
+    cmd = [
+        "cargo",
+        "test",
+        "-p",
+        "codewhale-tui",
+        "print_agent_tool_catalog_metrics",
+        "--",
+        "--ignored",
+        "--nocapture",
+        "--test-threads=1",
+    ]
+    proc = subprocess.run(cmd, text=True, capture_output=True, check=False)
+    sys.stderr.write(proc.stderr)
+
+    for line in proc.stdout.splitlines():
+        if MARKER in line:
+            metrics = json.loads(line.split(MARKER, 1)[1])
+            print(json.dumps(metrics, indent=2, sort_keys=True))
+            return proc.returncode
+
+    sys.stdout.write(proc.stdout)
+    sys.stderr.write("missing TOOL_CATALOG_METRICS marker\n")
+    return proc.returncode or 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/release/install.bat b/scripts/release/install.bat
new file mode 100644
index 00000000..69019415
--- /dev/null
+++ b/scripts/release/install.bat
@@ -0,0 +1,38 @@
+@echo off
+setlocal enabledelayedexpansion
+:: CodeWhale Windows installer
+:: Copies codewhale.exe and codewhale-tui.exe to %USERPROFILE%\bin
+
+set "BIN_DIR=%USERPROFILE%\bin"
+set "SCRIPT_DIR=%~dp0"
+
+if not exist "%BIN_DIR%" mkdir "%BIN_DIR%"
+
+echo Installing codewhale to %BIN_DIR%...
+
+copy /Y "%SCRIPT_DIR%codewhale.exe" "%BIN_DIR%\codewhale.exe" >nul
+if %ERRORLEVEL% neq 0 (
+    echo ERROR: Failed to copy codewhale.exe
+    exit /b 1
+)
+
+copy /Y "%SCRIPT_DIR%codewhale-tui.exe" "%BIN_DIR%\codewhale-tui.exe" >nul
+if %ERRORLEVEL% neq 0 (
+    echo ERROR: Failed to copy codewhale-tui.exe
+    exit /b 1
+)
+
+echo.
+echo Done. Both binaries installed to %BIN_DIR%.
+echo.
+echo Add %BIN_DIR% to your PATH:
+echo   1. Open Start, search "environment variables"
+echo   2. Click "Environment Variables..."
+echo   3. Under "User variables", select "Path" and click "Edit"
+echo   4. Click "New" and add: %BIN_DIR%
+echo   5. Click OK, then restart your terminal
+echo.
+echo Or run this in an admin PowerShell:
+echo   [Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ';%BIN_DIR%', 'User')
+echo.
+echo Then run: codewhale
diff --git a/scripts/release/install.sh b/scripts/release/install.sh
new file mode 100644
index 00000000..7841c76f
--- /dev/null
+++ b/scripts/release/install.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# CodeWhale Unix installer
+# Copies codewhale and codewhale-tui to ~/.local/bin (or $PREFIX/bin)
+
+PREFIX="${PREFIX:-$HOME/.local}"
+BIN_DIR="${PREFIX}/bin"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+mkdir -p "$BIN_DIR"
+
+echo "Installing codewhale to $BIN_DIR ..."
+
+for bin in codewhale codewhale-tui; do
+    src="$SCRIPT_DIR/$bin"
+    dst="$BIN_DIR/$bin"
+    if [[ ! -f "$src" ]]; then
+        echo "ERROR: $src not found in archive"
+        exit 1
+    fi
+    cp "$src" "$dst"
+    chmod +x "$dst"
+    echo "  $dst"
+done
+
+echo ""
+echo "Done. Both binaries installed to $BIN_DIR."
+
+# Check if BIN_DIR is on PATH
+if [[ ":$PATH:" != *":$BIN_DIR:"* ]]; then
+    echo ""
+    echo "Add $BIN_DIR to your PATH:"
+    echo ""
+    SHELL_NAME="$(basename "${SHELL:-$SHELL}")"
+    case "$SHELL_NAME" in
+        zsh)  RC="$HOME/.zshrc" ;;
+        bash) RC="$HOME/.bashrc" ;;
+        fish) RC="$HOME/.config/fish/config.fish" ;;
+        *)    RC="your shell profile" ;;
+    esac
+    echo "  echo 'export PATH=\"$BIN_DIR:\$PATH\"' >> $RC"
+    echo "  source $RC"
+fi
+
+echo ""
+echo "Then run: codewhale"
diff --git a/scripts/verify_task.sh b/scripts/verify_task.sh
new file mode 100644
index 00000000..97689ebf
--- /dev/null
+++ b/scripts/verify_task.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+# verify_task.sh <task_id> <docker_image>
+# Runs the DeepSWE verifier inside the task's Docker container.
+# Expects model.patch at /tmp/deep-swe-verify/<task_id>/model.patch
+TASK_ID="$1"
+IMAGE="$2"
+TASKS_DIR="/Volumes/VIXinSSD/whalebro/codewhale/deep-swe/tasks"
+WORK_DIR="/tmp/deep-swe-verify/$TASK_ID"
+
+mkdir -p "$WORK_DIR"
+RESULT_FILE="$WORK_DIR/result.txt"
+
+echo "[$TASK_ID] Pulling image..."
+docker pull "$IMAGE" 2>&1 | tail -1
+
+echo "[$TASK_ID] Running verifier..."
+docker run --rm \
+  --platform linux/amd64 \
+  -v "$WORK_DIR/model.patch:/model.patch:ro" \
+  -v "$TASKS_DIR/$TASK_ID/tests/test.patch:/tests/test.patch:ro" \
+  -v "$TASKS_DIR/$TASK_ID/tests/test.sh:/verify.sh:ro" \
+  "$IMAGE" \
+  bash -c '
+    set -e
+    mkdir -p /logs/verifier /logs/artifacts
+    cd /app
+    git apply --whitespace=nowarn /model.patch 2>/dev/null || { echo "PATCH_FAILED"; exit 2; }
+    bash /verify.sh > /logs/verifier/output.txt 2>&1
+    EC=$?
+    if [ -f /logs/verifier/reward.txt ]; then
+      REWARD=$(cat /logs/verifier/reward.txt)
+      echo "REWARD=$REWARD"
+    else
+      # Extract from output
+      if grep -q "New tests exit code: 0" /logs/verifier/output.txt && \
+         grep -q "Baseline exit code: 0" /logs/verifier/output.txt; then
+        echo "REWARD=1"
+      else
+        echo "REWARD=0"
+      fi
+    fi
+    echo "---OUTPUT_TAIL---"
+    tail -30 /logs/verifier/output.txt
+  ' > "$RESULT_FILE" 2>&1
+
+echo "[$TASK_ID] Done. Result:"
+cat "$RESULT_FILE" | grep -E 'REWARD|FAILED|PATCH_FAILED|passed'
+echo ""
diff --git a/web/app/[locale]/faq/page.tsx b/web/app/[locale]/faq/page.tsx
index 4a3af70c..f216552a 100644
--- a/web/app/[locale]/faq/page.tsx
+++ b/web/app/[locale]/faq/page.tsx
@@ -196,11 +196,11 @@ default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
     sources: ["README.md", "#1207"],
   },
   {
-    q: "What is Goal mode? Is it available?",
+    q: "What does /goal do?",
     a: (
       <>
-        Goal mode is a future workflow/tab direction for long-running, multi-step objectives — not the current <code className="inline">/goal</code> command.
-        The current <code className="inline">/goal</code> is a simple goal-setter. The full Goal mode (autonomous multi-turn task execution with checkpoint/resume) is planned but not yet implemented.
+        <code className="inline">/goal</code> is a simple goal-setter for the current session.
+        It does not add another app mode; the mode switcher remains Plan, Agent, and YOLO.
         Track progress in <a href="https://github.com/Hmbown/CodeWhale/issues/891" className="body-link">#891</a>.
       </>
     ),
diff --git a/web/app/[locale]/layout.tsx b/web/app/[locale]/layout.tsx
index 28e163ad..8eb0b1e7 100644
--- a/web/app/[locale]/layout.tsx
+++ b/web/app/[locale]/layout.tsx
@@ -11,16 +11,16 @@ export async function generateMetadata({ params }: { params: Promise<{ locale: s
   const { locale } = await params;
   const isZh = locale === "zh";
   return {
-    title: isZh ? "CodeWhale · 终端原生编程智能体" : "CodeWhale · 深度求索 终端",
+    title: isZh ? "CodeWhale · DeepSeek V4 智能体运行框架" : "CodeWhale · DeepSeek V4 智能体运行框架",
     description: isZh
-      ? "面向开源模型的终端编程智能体。DeepSeek V4 为一级模型。支持 100 万 token 上下文、MCP 协议、沙箱执行。"
-      : "Terminal-native coding agent for open-source and open-weight models across providers. DeepSeek V4 is first-class. Community site for installation, docs, roadmap, and live activity.",
+      ? "DeepSeek V4 的最强智能体运行框架。宪政层级、结构化信任、验证与恢复——让模型持续工作并不断进步的规则、工具和反馈循环。国际开源社区，递归自改进。"
+      : "The most agentic harness for DeepSeek V4. Constitutional hierarchy, structured trust, verification, and recovery — rules, tools, and feedback loops that help the model keep working. An international open source community building a recursive, self-improving harness.",
     metadataBase: new URL("https://codewhale.net"),
     openGraph: {
-      title: isZh ? "CodeWhale · 终端原生编程智能体" : "CodeWhale",
+      title: "CodeWhale",
       description: isZh
-        ? "面向开源模型的终端编程智能体。"
-        : "Terminal-native coding agent for open-source and open-weight models across providers.",
+        ? "DeepSeek V4 的最强智能体运行框架。宪政层级、结构化信任、验证与恢复。"
+        : "The most agentic harness for DeepSeek V4. Constitutional hierarchy, structured trust, verification, and recovery.",
       url: "https://codewhale.net",
       siteName: "CodeWhale",
       type: "website",
diff --git a/web/app/[locale]/page.tsx b/web/app/[locale]/page.tsx
index 05762720..85b6c300 100644
--- a/web/app/[locale]/page.tsx
+++ b/web/app/[locale]/page.tsx
@@ -87,18 +87,33 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
 
             <h1 className="font-display tracking-crisp">
               {isZh
-                ? "面向开源模型的终端编程智能体。"
-                : "The terminal coding agent for open models."}
+                ? "DeepSeek V4 的最强智能体运行框架。"
+                : "The most agentic harness for DeepSeek V4."}
             </h1>
 
             <p className="mt-6 text-lg text-ink-soft leading-relaxed max-w-2xl">
               <span className="font-cjk text-indigo font-semibold">CodeWhale</span>
               {isZh
-                ? " 是面向 DeepSeek V4 及其他开放权重模型的终端原生编程智能体。它读改文件、跑测试、调用 MCP 服务器，全程在你的文件系统沙箱内运行。"
-                : " is a terminal-native coding agent for DeepSeek V4 and other open-weight models. It reads and edits files, runs tests, calls MCP servers — all inside your filesystem sandbox."}
+                ? " 就是那个框架——围绕 DeepSeek V4 Pro 和 Flash 构建，用规则、工具、证据和反馈循环让模型持续工作并不断进步。DeepSeek V4 参与了编写。V4 越强，框架越强——每一轮对话留下更好的提示词和更清晰的交接，下一轮从更高起点出发。这个递归循环正是项目的核心使命：借助国际开源社区，构建一个让 V4 自主管理环境的自改进框架。"
+                : " is that harness — built around DeepSeek V4 Pro and Flash, with rules, tools, evidence, and feedback loops that help the model keep working and keep improving. DeepSeek V4 helped write it. As V4 improves, the harness improves with it. Each turn leaves behind better prompts and better handoffs — so the next turn starts stronger. That's the recursive loop at the heart of this project: an international open source community building a harness that lets V4 manage its own environment, turn after turn."}
             </p>
 
-            <div className="mt-8 flex flex-wrap items-stretch sm:items-center gap-3">
+            {/* MISSION CALLOUT */}
+            <div className="mt-6 px-4 py-3 bg-indigo-pale border-l-4 border-indigo text-sm leading-relaxed max-w-2xl">
+              {isZh ? (
+                <>
+                  <span className="font-display text-indigo font-semibold mr-1">使命</span>
+                  构建一个递归自改进的 DeepSeek V4 运行框架——通过国际开源社区的力量，让 V4 在每一轮对话中学会更好地管理自己的环境。
+                </>
+              ) : (
+                <>
+                  <span className="font-display text-indigo font-semibold mr-1">Mission</span>
+                  Build a recursive, self-improving harness for DeepSeek V4 — by leveraging the international open source community and V4's own ability to manage its environment, turn after turn.
+                </>
+              )}
+            </div>
+
+            <div className="mt-6 flex flex-wrap items-stretch sm:items-center gap-3">
               <Link
                 href={isZh ? "/zh/install" : "/install"}
                 className="flex-1 sm:flex-none text-center px-5 py-3 bg-ink text-paper font-mono text-sm uppercase tracking-wider hover:bg-indigo transition-colors"
@@ -165,61 +180,66 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
 
       <StatGrid stats={stats} />
 
-      {/* WHAT IT IS */}
+      {/* WHAT IT IS — the core ideas behind the harness */}
       <section className="mx-auto max-w-[1400px] px-6 py-16">
-        <div className="flex items-baseline gap-4 mb-8 hairline-b pb-4">
+        <div className="flex items-baseline gap-4 mb-2 hairline-b pb-4">
           <Seal char="是" />
           <h2 className="font-display">
-            {isZh ? "它到底是什么" : "What it actually is"}
+            {isZh ? "核心思想" : "The ideas that make it what it is"}
           </h2>
         </div>
+        <p className={`mb-8 text-ink-soft max-w-2xl ${isZh ? "leading-[1.9] tracking-wide" : "text-sm leading-relaxed"}`}>
+          {isZh
+            ? "一个模型回答问题，一个智能体完成任务。区别在于框架——围绕模型构建的规则、工具、证据和反馈循环的运行环境。CodeWhale 围绕三条原则运作。"
+            : "A model answers a question. An agent finishes a task. The difference is the harness — the operating environment that surrounds the model with rules, tools, evidence, and feedback loops. CodeWhale operates on three principles."}
+        </p>
 
         <div className="grid md:grid-cols-3 gap-0 col-rule hairline-t hairline-b">
           {isZh ? (
             <>
               <div className="p-6">
-                <div className="eyebrow mb-3">01 · 终端智能体</div>
-                <h3 className="font-display text-xl mb-3">编程智能体，不是聊天框</h3>
+                <div className="eyebrow mb-3">01 · 宪政层级</div>
+                <h3 className="font-display text-xl mb-3">七层权威链，从不模糊</h3>
                 <p className="text-sm text-ink-soft leading-[1.9]">
-                  与 Claude Code、Codex CLI 相同的循环：读、改、跑测试、回报。键盘驱动，住在终端里。
+                  《宪法》第七条定义了九层权威层级——用户当前消息覆盖过时项目规则，实时工具输出覆盖假设，验证覆盖自信。模型不需要猜测该服从哪条指令。
                 </p>
               </div>
               <div className="p-6">
-                <div className="eyebrow mb-3">02 · 开源模型优先</div>
-                <h3 className="font-display text-xl mb-3">DeepSeek V4 深度集成</h3>
+                <div className="eyebrow mb-3">02 · 自己写的框架</div>
+                <h3 className="font-display text-xl mb-3">DeepSeek V4 参与构建</h3>
                 <p className="text-sm text-ink-soft leading-[1.9]">
-                  原生 DeepSeek API：推理流、缓存指标、思考力度控制。OpenRouter、NVIDIA NIM、vLLM、sglang 同时可选。
+                  V4 编写了框架的部分代码。每一轮对话的缓存前缀让《宪法》的实际成本接近免费。V4 越强，框架越强；框架越强，V4 在其中越高效——递归循环。
                 </p>
               </div>
               <div className="p-6">
-                <div className="eyebrow mb-3">03 · 沙箱边界</div>
-                <h3 className="font-display text-xl mb-3">Plan、Agent、YOLO</h3>
+                <div className="eyebrow mb-3">03 · 开源协作</div>
+                <h3 className="font-display text-xl mb-3">国际社区，小补丁驱动</h3>
                 <p className="text-sm text-ink-soft leading-[1.9]">
-                  Plan 只读；Agent 风险操作前确认；YOLO 全自动。沙箱：seatbelt（macOS）、landlock（Linux）、受限令牌（Windows）。
+                  100:1 贡献模型——一个提示词、大量智能体小时、一个小补丁、一次维护者审查。无 CLA，无赞助商优先通道。每一条内容都被阅读。
                 </p>
               </div>
             </>
           ) : (
             <>
               <div className="p-6">
-                <div className="eyebrow mb-3">01 · terminal agent</div>
-                <h3 className="font-display text-xl mb-3">A coding agent, not a chat box</h3>
+                <div className="eyebrow mb-3">01 · constitutional hierarchy</div>
+                <h3 className="font-display text-xl mb-3">Seven tiers of authority, never ambiguous</h3>
                 <p className="text-sm text-ink-soft leading-relaxed">
-                  Same loop as Claude Code or Codex CLI: reads, edits, runs tests, reports back. Keyboard-driven, lives in your terminal.
+                  Article VII of the Constitution ranks nine sources from the Articles themselves to prior-session handoffs. The user's current message outranks stale project rules. Live tool output outranks assumptions. Verification outranks confidence. The model never guesses which instruction to follow.
                 </p>
               </div>
               <div className="p-6">
-                <div className="eyebrow mb-3">02 · open models first</div>
-                <h3 className="font-display text-xl mb-3">DeepSeek V4, deeply integrated</h3>
+                <div className="eyebrow mb-3">02 · self-written harness</div>
+                <h3 className="font-display text-xl mb-3">DeepSeek V4 helped build it</h3>
                 <p className="text-sm text-ink-soft leading-relaxed">
-                  Native DeepSeek API: reasoning streaming, cache metrics, thinking-effort control. OpenRouter, NVIDIA NIM, vLLM, and sglang also supported.
+                  V4 wrote parts of this harness. DeepSeek's prefix caching makes the Constitution nearly free to reference every turn. As V4 improves, the harness improves with it. A more effective V4 makes the harness better — the recursive loop that defines this project.
                 </p>
               </div>
               <div className="p-6">
-                <div className="eyebrow mb-3">03 · sandboxed</div>
-                <h3 className="font-display text-xl mb-3">Plan, Agent, YOLO</h3>
+                <div className="eyebrow mb-3">03 · open by design</div>
+                <h3 className="font-display text-xl mb-3">International community, small patches</h3>
                 <p className="text-sm text-ink-soft leading-relaxed">
-                  Plan reads only. Agent asks before risky ops. YOLO auto-approves. Sandboxed via seatbelt (macOS), landlock (Linux), restricted tokens (Windows).
+                  The 100-to-1 contribution model: one prompt, many agent-hours, one small patch, one maintainer review. No CLA. No sponsor lockouts. The maintainer reads everything personally, issues are triaged in the open, releases cut from main.
                 </p>
               </div>
             </>
@@ -260,6 +280,11 @@ export default async function HomePage({ params }: { params: Promise<{ locale: s
                   ? "100:1 不是性能基准，而是贡献形状：一个提示词、许多智能体小时、一个小补丁、一次维护者审查。"
                   : "100-to-1 is not a throughput benchmark. It is a contribution shape: one prompt, many agent-hours, one small patch, one maintainer review."}
               </p>
+              <p className={`mt-4 text-sm text-ink-soft ${isZh ? "leading-[1.9] tracking-wide" : "leading-relaxed"}`}>
+                {isZh
+                  ? "框架承担了繁重工作：宪政提示、结构化信任、反馈循环和跨会话存活的交接。模型可以专注于任务本身。因为 DeepSeek V4 参与构建了这套框架，每一次改进都让 V4 在其中变得更有效——这让下一次改进变得更容易。"
+                  : "The harness does the heavy lifting: constitutional prompts, structured trust, feedback loops, and handoffs that survive the session. The model is free to focus on the task. And because DeepSeek V4 helped build this harness, each improvement makes V4 more effective within it — which makes the next improvement easier."}
+              </p>
               <div className="mt-6 flex flex-wrap gap-3">
                 <Link href={isZh ? "/zh/contribute#recursive-harness" : "/contribute#recursive-harness"} className="px-4 py-2 bg-ink text-paper font-mono text-sm uppercase tracking-wider hover:bg-indigo transition-colors">
                   {isZh ? "运行提示词 →" : "Run the prompt →"}
diff --git a/web/app/layout.tsx b/web/app/layout.tsx
index 9dfc2ab7..214aceef 100644
--- a/web/app/layout.tsx
+++ b/web/app/layout.tsx
@@ -33,13 +33,13 @@ const cjk = Noto_Serif_SC({
 });
 
 export const metadata: Metadata = {
-  title: "CodeWhale · 深度求索 终端",
+  title: "CodeWhale · DeepSeek V4 智能体运行框架",
   description:
-    "Terminal-native coding agent for open-source and open-weight models across providers. DeepSeek V4 is first-class. Community site for installation, docs, roadmap, and live activity.",
+    "The most agentic harness for DeepSeek V4. Constitutional hierarchy, structured trust, verification, and recovery — rules, tools, and feedback loops that help the model keep working.",
   metadataBase: new URL("https://codewhale.net"),
   openGraph: {
     title: "CodeWhale",
-    description: "Terminal-native coding agent for open-source and open-weight models across providers.",
+    description: "The most agentic harness for DeepSeek V4. Constitutional hierarchy, structured trust, verification, and recovery.",
     url: "https://codewhale.net",
     siteName: "CodeWhale",
     type: "website",
diff --git a/web/components/install-binary.tsx b/web/components/install-binary.tsx
index 0e36afaa..16bad1b5 100644
--- a/web/components/install-binary.tsx
+++ b/web/components/install-binary.tsx
@@ -8,22 +8,30 @@ type Arch = "macos-arm64" | "macos-x64" | "linux-x64" | "linux-arm64" | "windows
 const SNIPPETS: Record<Arch, string> = {
   "macos-arm64": `curl -fsSL -o codewhale \\
   https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-macos-arm64
-chmod +x codewhale
-xattr -d com.apple.quarantine codewhale 2>/dev/null || true
-sudo mv codewhale /usr/local/bin/`,
+curl -fsSL -o codewhale-tui \\
+  https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-macos-arm64
+chmod +x codewhale codewhale-tui
+xattr -d com.apple.quarantine codewhale codewhale-tui 2>/dev/null || true
+sudo mv codewhale codewhale-tui /usr/local/bin/`,
   "macos-x64": `curl -fsSL -o codewhale \\
   https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-macos-x64
-chmod +x codewhale
-xattr -d com.apple.quarantine codewhale 2>/dev/null || true
-sudo mv codewhale /usr/local/bin/`,
+curl -fsSL -o codewhale-tui \\
+  https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-macos-x64
+chmod +x codewhale codewhale-tui
+xattr -d com.apple.quarantine codewhale codewhale-tui 2>/dev/null || true
+sudo mv codewhale codewhale-tui /usr/local/bin/`,
   "linux-x64": `curl -fsSL -o codewhale \\
   https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-x64
-chmod +x codewhale
-sudo mv codewhale /usr/local/bin/`,
+curl -fsSL -o codewhale-tui \\
+  https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-linux-x64
+chmod +x codewhale codewhale-tui
+sudo mv codewhale codewhale-tui /usr/local/bin/`,
   "linux-arm64": `curl -fsSL -o codewhale \\
   https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-arm64
-chmod +x codewhale
-sudo mv codewhale /usr/local/bin/`,
+curl -fsSL -o codewhale-tui \\
+  https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-linux-arm64
+chmod +x codewhale codewhale-tui
+sudo mv codewhale codewhale-tui /usr/local/bin/`,
   "windows-x64": `# PowerShell
 $ErrorActionPreference = "Stop"
 $dest = "$Env:USERPROFILE\\bin"
@@ -32,6 +40,9 @@ New-Item -ItemType Directory -Force $dest | Out-Null
 Invoke-WebRequest \`
   -Uri https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-windows-x64.exe \`
   -OutFile "$dest\\codewhale.exe"
+Invoke-WebRequest \`
+  -Uri https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-windows-x64.exe \`
+  -OutFile "$dest\\codewhale-tui.exe"
 
 $Env:Path = "$dest;$Env:Path"`,
 };
@@ -46,7 +57,8 @@ sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing`,
   "linux-arm64": `curl -fsSL -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
 sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing`,
   "windows-x64": `# PowerShell
-Get-FileHash "$Env:USERPROFILE\\bin\\codewhale.exe" -Algorithm SHA256`,
+Get-FileHash "$Env:USERPROFILE\\bin\\codewhale.exe" -Algorithm SHA256
+Get-FileHash "$Env:USERPROFILE\\bin\\codewhale-tui.exe" -Algorithm SHA256`,
 };
 
 const LABELS: Record<Arch, string> = {
@@ -103,4 +115,4 @@ export function InstallBinary({ copyLabel, copiedLabel, verifyHeading = "Verify
       </div>
     </div>
   );
-}
+}
\ No newline at end of file
diff --git a/web/components/install-download-tile.tsx b/web/components/install-download-tile.tsx
new file mode 100644
index 00000000..ca56ab82
--- /dev/null
+++ b/web/components/install-download-tile.tsx
@@ -0,0 +1,159 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+type Arch = "macos-arm64" | "macos-x64" | "linux-x64" | "linux-arm64" | "windows-x64";
+
+const BASE =
+  "https://github.com/Hmbown/CodeWhale/releases/latest/download";
+
+const ASSETS: Record<Arch, { zip: string; sha: string }> = {
+  "macos-arm64": {
+    zip: `${BASE}/codewhale-macos-arm64.zip`,
+    sha: `${BASE}/codewhale-artifacts-sha256.txt`,
+  },
+  "macos-x64": {
+    zip: `${BASE}/codewhale-macos-x64.zip`,
+    sha: `${BASE}/codewhale-artifacts-sha256.txt`,
+  },
+  "linux-x64": {
+    zip: `${BASE}/codewhale-linux-x64.zip`,
+    sha: `${BASE}/codewhale-artifacts-sha256.txt`,
+  },
+  "linux-arm64": {
+    zip: `${BASE}/codewhale-linux-arm64.zip`,
+    sha: `${BASE}/codewhale-artifacts-sha256.txt`,
+  },
+  "windows-x64": {
+    zip: `${BASE}/codewhale-windows-x64.zip`,
+    sha: `${BASE}/codewhale-artifacts-sha256.txt`,
+  },
+};
+
+const LABELS: Record<Arch, string> = {
+  "macos-arm64": "macOS · Apple Silicon",
+  "macos-x64": "macOS · Intel",
+  "linux-x64": "Linux · x64",
+  "linux-arm64": "Linux · arm64",
+  "windows-x64": "Windows · x64",
+};
+
+function detect(): Arch {
+  if (typeof navigator === "undefined") return "macos-arm64";
+  const ua = navigator.userAgent.toLowerCase();
+  if (ua.includes("win")) return "windows-x64";
+  if (ua.includes("linux")) {
+    if (ua.includes("aarch64") || ua.includes("arm64")) return "linux-arm64";
+    return "linux-x64";
+  }
+  return "macos-arm64";
+}
+
+interface Props {
+  heading: string;
+  downloadLabel: string;
+  sha256Label: string;
+  mirrorHeading: string;
+  mirrorGhproxy: string;
+  mirrorJsdelivr: string;
+  offlineCallout: string;
+}
+
+export function InstallDownloadTile({
+  heading,
+  downloadLabel,
+  sha256Label,
+  mirrorHeading,
+  mirrorGhproxy,
+  mirrorJsdelivr,
+  offlineCallout,
+}: Props) {
+  const [arch, setArch] = useState<Arch>("macos-arm64");
+
+  useEffect(() => {
+    setArch(detect());
+  }, []);
+
+  const { zip, sha } = ASSETS[arch];
+  const ghproxy = `https://ghproxy.com/${zip}`;
+
+  return (
+    <div>
+      {/* Arch selector tabs */}
+      <div className="flex flex-wrap gap-0 mb-6 hairline-t hairline-b hairline-l hairline-r">
+        {(Object.keys(LABELS) as Arch[]).map((a, i) => (
+          <button
+            key={a}
+            onClick={() => setArch(a)}
+            className={`px-3 py-1.5 font-mono text-[0.7rem] tracking-wider transition-colors ${
+              i > 0 ? "hairline-l" : ""
+            } ${arch === a ? "bg-ink text-paper" : "bg-paper hover:bg-paper-deep"}`}
+          >
+            {LABELS[a]}
+          </button>
+        ))}
+      </div>
+
+      <h2 className="font-display text-3xl mb-2">{heading}</h2>
+
+      {/* Download button */}
+      <div className="flex flex-wrap items-center gap-4 mt-6 mb-4">
+        <a
+          href={zip}
+          className="inline-flex items-center gap-2 px-5 py-3 bg-ink text-paper font-mono text-sm tracking-wide hover:bg-indigo transition-colors"
+          download
+        >
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden>
+            <path
+              d="M8 1v9M4 7l4 4 4-4M2 12v2h12v-2"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+          {downloadLabel} (.zip)
+        </a>
+
+        <a
+          href={sha}
+          className="font-mono text-[0.7rem] uppercase tracking-wider text-ink-mute hover:text-indigo transition-colors"
+        >
+          {sha256Label} →
+        </a>
+      </div>
+
+      {/* China mirror links */}
+      <div className="mt-6">
+        <div className="eyebrow mb-2">{mirrorHeading}</div>
+        <div className="flex flex-wrap gap-3">
+          <a
+            href={ghproxy}
+            className="inline-flex items-center gap-1.5 px-3 py-2 text-xs font-mono hairline-t hairline-b hairline-l hairline-r hover:bg-paper-deep transition-colors"
+            rel="noopener noreferrer"
+            target="_blank"
+          >
+            {mirrorGhproxy}
+          </a>
+          <span className="text-xs text-ink-mute self-center">
+            {/* jsdelivr doesn't directly proxy GitHub Release assets; link to the release page instead */}
+            <a
+              href={`https://github.com/Hmbown/CodeWhale/releases/latest`}
+              className="inline-flex items-center gap-1.5 px-3 py-2 text-xs font-mono hairline-t hairline-b hairline-l hairline-r hover:bg-paper-deep transition-colors"
+              rel="noopener noreferrer"
+              target="_blank"
+            >
+              {mirrorJsdelivr}
+            </a>
+          </span>
+        </div>
+      </div>
+
+      {/* Offline callout */}
+      <div className="mt-6 px-4 py-3 bg-indigo-pale text-sm leading-relaxed">
+        <span className="font-display text-indigo mr-2">💡</span>
+        {offlineCallout}
+      </div>
+    </div>
+  );
+}
diff --git a/web/lib/facts-drift.ts b/web/lib/facts-drift.ts
index 5e99f35c..531ebcff 100644
--- a/web/lib/facts-drift.ts
+++ b/web/lib/facts-drift.ts
@@ -77,12 +77,15 @@ function deriveProvidersFromConfig(cfg: string): ProviderFact[] {
   // so the binary rejects it — keep it out of the docs. Issue #1104.
   const labelMap: Record<string, ProviderFact> = {
     Deepseek: { id: "deepseek", label: "DeepSeek", env: "DEEPSEEK_API_KEY" },
-    NvidiaNim: { id: "nvidia-nim", label: "NVIDIA NIM", env: "NVIDIA_API_KEY" },
-    Openai: { id: "openai", label: "OpenAI", env: "OPENAI_API_KEY" },
+    NvidiaNim: { id: "nvidia-nim", label: "NVIDIA NIM", env: "NVIDIA_API_KEY / NVIDIA_NIM_API_KEY" },
+    Openai: { id: "openai", label: "OpenAI-compatible", env: "OPENAI_API_KEY" },
+    Atlascloud: { id: "atlascloud", label: "AtlasCloud", env: "ATLASCLOUD_API_KEY" },
+    WanjieArk: { id: "wanjie-ark", label: "Wanjie Ark", env: "WANJIE_ARK_API_KEY / WANJIE_API_KEY / WANJIE_MAAS_API_KEY" },
     Openrouter: { id: "openrouter", label: "OpenRouter", env: "OPENROUTER_API_KEY" },
-    Novita: { id: "novita", label: "Novita", env: "NOVITA_API_KEY" },
-    Fireworks: { id: "fireworks", label: "Fireworks", env: "FIREWORKS_API_KEY" },
-    Sglang: { id: "sglang", label: "sglang", env: "SGLANG_API_KEY" },
+    Novita: { id: "novita", label: "Novita AI", env: "NOVITA_API_KEY" },
+    Fireworks: { id: "fireworks", label: "Fireworks AI", env: "FIREWORKS_API_KEY" },
+    Moonshot: { id: "moonshot", label: "Moonshot/Kimi", env: "MOONSHOT_API_KEY / KIMI_API_KEY" },
+    Sglang: { id: "sglang", label: "SGLang", env: "SGLANG_API_KEY" },
     Vllm: { id: "vllm", label: "vLLM", env: "VLLM_API_KEY" },
     Ollama: { id: "ollama", label: "Ollama", env: "OLLAMA_API_KEY" },
   };
@@ -98,7 +101,6 @@ function deriveSandboxBackends(files: string[]): string[] {
   const map: Record<string, string> = {
     seatbelt: "seatbelt (macOS)",
     landlock: "landlock (Linux)",
-    windows: "AppContainer / restricted tokens (Windows)",
   };
   return files
     .map((f) => f.replace(/\.rs$/, ""))
diff --git a/web/lib/facts.generated.ts b/web/lib/facts.generated.ts
index b4468cf9..d7cbe216 100644
--- a/web/lib/facts.generated.ts
+++ b/web/lib/facts.generated.ts
@@ -18,8 +18,8 @@ export interface RepoFacts {
 }
 
 export const FACTS: RepoFacts = {
-  "generatedAt": "2026-05-24T16:01:45.189Z",
-  "version": "0.8.43",
+  "generatedAt": "2026-05-26T17:03:21.939Z",
+  "version": "0.8.46",
   "crates": [
     "agent",
     "app-server",
@@ -37,9 +37,11 @@ export const FACTS: RepoFacts = {
     "tui-core"
   ],
   "sandboxBackends": [
+    "bwrap",
     "landlock (Linux)",
+    "process_hardening",
     "seatbelt (macOS)",
-    "AppContainer / restricted tokens (Windows)"
+    "seccomp"
   ],
   "providers": [
     {
@@ -50,13 +52,23 @@ export const FACTS: RepoFacts = {
     {
       "id": "nvidia-nim",
       "label": "NVIDIA NIM",
-      "env": "NVIDIA_API_KEY"
+      "env": "NVIDIA_API_KEY / NVIDIA_NIM_API_KEY"
     },
     {
       "id": "openai",
-      "label": "OpenAI",
+      "label": "OpenAI-compatible",
       "env": "OPENAI_API_KEY"
     },
+    {
+      "id": "atlascloud",
+      "label": "AtlasCloud",
+      "env": "ATLASCLOUD_API_KEY"
+    },
+    {
+      "id": "wanjie-ark",
+      "label": "Wanjie Ark",
+      "env": "WANJIE_ARK_API_KEY / WANJIE_API_KEY / WANJIE_MAAS_API_KEY"
+    },
     {
       "id": "openrouter",
       "label": "OpenRouter",
@@ -64,17 +76,22 @@ export const FACTS: RepoFacts = {
     },
     {
       "id": "novita",
-      "label": "Novita",
+      "label": "Novita AI",
       "env": "NOVITA_API_KEY"
     },
     {
       "id": "fireworks",
-      "label": "Fireworks",
+      "label": "Fireworks AI",
       "env": "FIREWORKS_API_KEY"
     },
+    {
+      "id": "moonshot",
+      "label": "Moonshot/Kimi",
+      "env": "MOONSHOT_API_KEY / KIMI_API_KEY"
+    },
     {
       "id": "sglang",
-      "label": "sglang",
+      "label": "SGLang",
       "env": "SGLANG_API_KEY"
     },
     {
@@ -90,7 +107,7 @@ export const FACTS: RepoFacts = {
   ],
   "defaultModel": "deepseek-v4-pro",
   "nodeEngines": ">=18",
-  "toolCount": 69,
+  "toolCount": 70,
   "license": "MIT",
   "latestRelease": null
 };
diff --git a/web/lib/facts.ts b/web/lib/facts.ts
index 25ec174b..6e7514ce 100644
--- a/web/lib/facts.ts
+++ b/web/lib/facts.ts
@@ -11,6 +11,10 @@ interface KVNamespace {
 }
 
 async function getKv(): Promise<KVNamespace | undefined> {
+  if (process.env.NEXT_PHASE === "phase-production-build") {
+    return undefined;
+  }
+
   try {
     const mod = await import("@opennextjs/cloudflare");
     const ctx = await mod.getCloudflareContext({ async: true });
diff --git a/web/lib/github.ts b/web/lib/github.ts
index aeafe692..380c0004 100644
--- a/web/lib/github.ts
+++ b/web/lib/github.ts
@@ -2,7 +2,7 @@ import type { FeedItem, RepoStats } from "./types";
 
 const REPO = process.env.GITHUB_REPO ?? "Hmbown/CodeWhale";
 const GH = "https://api.github.com";
-const MIN_KNOWN_CONTRIBUTORS = 98;
+const MIN_KNOWN_CONTRIBUTORS = 99;
 
 function headers(token?: string): HeadersInit {
   const h: Record<string, string> = {
diff --git a/web/lib/kv.ts b/web/lib/kv.ts
index c6048b3a..f3a4bab6 100644
--- a/web/lib/kv.ts
+++ b/web/lib/kv.ts
@@ -23,20 +23,28 @@ interface CloudflareEnv {
   GITHUB_REPO?: string;
 }
 
+function envFromProcess(): CloudflareEnv {
+  return {
+    DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY,
+    DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL,
+    DEEPSEEK_MODEL: process.env.DEEPSEEK_MODEL,
+    GITHUB_TOKEN: process.env.GITHUB_TOKEN,
+    CRON_SECRET: process.env.CRON_SECRET,
+    GITHUB_REPO: process.env.GITHUB_REPO,
+  };
+}
+
 export async function getEnv(): Promise<CloudflareEnv> {
+  if (process.env.NEXT_PHASE === "phase-production-build") {
+    return envFromProcess();
+  }
+
   try {
     const mod = await import("@opennextjs/cloudflare");
     const ctx = await mod.getCloudflareContext({ async: true });
     return ctx.env as CloudflareEnv;
   } catch {
-    return {
-      DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY,
-      DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL,
-      DEEPSEEK_MODEL: process.env.DEEPSEEK_MODEL,
-      GITHUB_TOKEN: process.env.GITHUB_TOKEN,
-      CRON_SECRET: process.env.CRON_SECRET,
-      GITHUB_REPO: process.env.GITHUB_REPO,
-    };
+    return envFromProcess();
   }
 }
 
diff --git a/web/lib/roadmap-feed.ts b/web/lib/roadmap-feed.ts
index 102f1037..4c1e4606 100644
--- a/web/lib/roadmap-feed.ts
+++ b/web/lib/roadmap-feed.ts
@@ -55,6 +55,20 @@ async function gh<T>(url: string, ghToken?: string): Promise<T | null> {
 interface GhRelease { tag_name: string; name: string | null; body: string | null; html_url: string; prerelease: boolean; draft: boolean }
 interface GhIssue { number: number; title: string; html_url: string; body: string | null; state: string; pull_request?: unknown }
 
+const FALLBACK_SHIPPED: RoadmapItem[] = [
+  {
+    title: "v0.8.45",
+    note: "Moonshot/Kimi provider support, API-key setup guidance, provider-surface sync, and current Windows install/runtime guidance",
+    href: "https://github.com/Hmbown/CodeWhale/releases/tag/v0.8.45",
+  },
+];
+
+function withPinnedShipped(items: RoadmapItem[]): RoadmapItem[] {
+  const seen = new Set(items.map((item) => item.title));
+  const pinned = FALLBACK_SHIPPED.filter((item) => !seen.has(item.title));
+  return [...pinned, ...items];
+}
+
 function summarizeReleaseBody(body: string | null): string {
   if (!body) return "";
   // First non-empty line, stripped of markdown headers / bullets / links
@@ -100,17 +114,19 @@ export async function fetchRoadmap(ghToken?: string): Promise<RoadmapFeed> {
     fetchByLabel("roadmap:ruled-out", ghToken, "all"),
   ]);
 
-  const shipped: RoadmapItem[] = (releases ?? [])
+  const shipped: RoadmapItem[] = releases
+    ? releases
     .filter((r) => !r.draft)
     .map((r) => ({
       title: r.name?.trim() || r.tag_name,
       note: summarizeReleaseBody(r.body) || r.tag_name,
       href: r.html_url,
-    }));
+    }))
+    : FALLBACK_SHIPPED;
 
   return {
     generatedAt: new Date().toISOString(),
-    shipped,
+    shipped: withPinnedShipped(shipped),
     underway,
     considered,
     ruledOut,
@@ -121,7 +137,10 @@ export async function getCachedRoadmap(kv: KVNamespace | undefined, ghToken: str
   try {
     if (kv) {
       const cached = await kv.get(KV_KEY);
-      if (cached) return JSON.parse(cached) as RoadmapFeed;
+      if (cached) {
+        const parsed = JSON.parse(cached) as RoadmapFeed;
+        return { ...parsed, shipped: withPinnedShipped(parsed.shipped ?? []) };
+      }
     }
     const fresh = await fetchRoadmap(ghToken);
     if (kv) {
diff --git a/web/redirect/src/index.ts b/web/redirect/src/index.ts
new file mode 100644
index 00000000..07f803ab
--- /dev/null
+++ b/web/redirect/src/index.ts
@@ -0,0 +1,7 @@
+export default {
+  fetch(request: Request): Response {
+    const url = new URL(request.url);
+    url.host = "codewhale.net";
+    return Response.redirect(url.toString(), 301);
+  },
+};
diff --git a/web/redirect/wrangler.jsonc b/web/redirect/wrangler.jsonc
new file mode 100644
index 00000000..6d910310
--- /dev/null
+++ b/web/redirect/wrangler.jsonc
@@ -0,0 +1,11 @@
+{
+  "$schema": "../node_modules/wrangler/config-schema.json",
+  "name": "deepseek-tui-web",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-04-01",
+  "observability": { "enabled": true },
+  "routes": [
+    { "pattern": "deepseek-tui.com", "custom_domain": true },
+    { "pattern": "www.deepseek-tui.com", "custom_domain": true }
+  ]
+}
diff --git a/web/scripts/derive-facts.mjs b/web/scripts/derive-facts.mjs
index 76b31f2d..b1e7830d 100644
--- a/web/scripts/derive-facts.mjs
+++ b/web/scripts/derive-facts.mjs
@@ -46,10 +46,10 @@ function deriveSandboxBackends() {
   const files = readdirSync(dir)
     .filter((f) => f.endsWith(".rs"))
     .map((f) => f.replace(/\.rs$/, ""))
-    .filter((f) => !["mod", "policy", "backend", "opensandbox"].includes(f))
+    .filter((f) => !["mod", "policy", "backend", "opensandbox", "windows"].includes(f))
     .sort();
   // canonicalize platform names
-  const map = { seatbelt: "seatbelt (macOS)", landlock: "landlock (Linux)", windows: "AppContainer / restricted tokens (Windows)" };
+  const map = { seatbelt: "seatbelt (macOS)", landlock: "landlock (Linux)" };
   return files.map((f) => map[f] ?? f);
 }
 
@@ -66,12 +66,15 @@ function deriveProviders() {
   // shared ProviderKind, so we exclude it until that lands. Issue #1104.
   const labelMap = {
     Deepseek: { id: "deepseek", label: "DeepSeek", env: "DEEPSEEK_API_KEY" },
-    NvidiaNim: { id: "nvidia-nim", label: "NVIDIA NIM", env: "NVIDIA_API_KEY" },
-    Openai: { id: "openai", label: "OpenAI", env: "OPENAI_API_KEY" },
+    NvidiaNim: { id: "nvidia-nim", label: "NVIDIA NIM", env: "NVIDIA_API_KEY / NVIDIA_NIM_API_KEY" },
+    Openai: { id: "openai", label: "OpenAI-compatible", env: "OPENAI_API_KEY" },
+    Atlascloud: { id: "atlascloud", label: "AtlasCloud", env: "ATLASCLOUD_API_KEY" },
+    WanjieArk: { id: "wanjie-ark", label: "Wanjie Ark", env: "WANJIE_ARK_API_KEY / WANJIE_API_KEY / WANJIE_MAAS_API_KEY" },
     Openrouter: { id: "openrouter", label: "OpenRouter", env: "OPENROUTER_API_KEY" },
-    Novita: { id: "novita", label: "Novita", env: "NOVITA_API_KEY" },
-    Fireworks: { id: "fireworks", label: "Fireworks", env: "FIREWORKS_API_KEY" },
-    Sglang: { id: "sglang", label: "sglang", env: "SGLANG_API_KEY" },
+    Novita: { id: "novita", label: "Novita AI", env: "NOVITA_API_KEY" },
+    Fireworks: { id: "fireworks", label: "Fireworks AI", env: "FIREWORKS_API_KEY" },
+    Moonshot: { id: "moonshot", label: "Moonshot/Kimi", env: "MOONSHOT_API_KEY / KIMI_API_KEY" },
+    Sglang: { id: "sglang", label: "SGLang", env: "SGLANG_API_KEY" },
     Vllm: { id: "vllm", label: "vLLM", env: "VLLM_API_KEY" },
     Ollama: { id: "ollama", label: "Ollama", env: "OLLAMA_API_KEY" },
   };
diff --git a/web/wrangler.jsonc b/web/wrangler.jsonc
index 6014a3a8..a4073b9d 100644
--- a/web/wrangler.jsonc
+++ b/web/wrangler.jsonc
@@ -1,6 +1,6 @@
 {
   "$schema": "node_modules/wrangler/config-schema.json",
-  "name": "deepseek-tui-web",
+  "name": "codewhale-web",
   "main": "worker.ts",
   "compatibility_date": "2025-04-01",
   "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
@@ -9,6 +9,10 @@
     "binding": "ASSETS"
   },
   "observability": { "enabled": true },
+  "routes": [
+    { "pattern": "codewhale.net", "custom_domain": true },
+    { "pattern": "www.codewhale.net", "custom_domain": true }
+  ],
   "kv_namespaces": [
     {
       "binding": "CURATED_KV",
@@ -22,7 +26,7 @@
   "vars": {
     "GITHUB_REPO": "Hmbown/CodeWhale",
     "DEEPSEEK_MODEL": "deepseek-v4-flash",
-    "DEEPSEEK_BASE_URL": "https://gateway.ai.cloudflare.com/v1/cf50f793171d7cb3b2ce23368b69cdcb/deepseek-tui-web/deepseek"
+    "DEEPSEEK_BASE_URL": "https://gateway.ai.cloudflare.com/v1/cf50f793171d7cb3b2ce23368b69cdcb/codewhale-web/deepseek"
   },
   "triggers": {
     "crons": [
diff --git a/website/index.html b/website/index.html
deleted file mode 100644
index 39351284..00000000
--- a/website/index.html
+++ /dev/null
@@ -1,568 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>DeepSeek TUI — Terminal-native coding agent</title>
-  <link rel="alternate" hreflang="zh" href="./zh/">
-  <style>
-    :root {
-      --bg: #0a0e14;
-      --bg-elevated: #111820;
-      --bg-card: #0f151c;
-      --border: #1e2a36;
-      --border-light: #263545;
-      --text: #b8c5d6;
-      --text-muted: #5e7a94;
-      --text-bright: #e8f0f8;
-      --accent: #4dabf7;
-      --accent-dim: #1971c2;
-      --accent-glow: rgba(77, 171, 247, 0.15);
-      --success: #51cf66;
-      --warning: #ffd43b;
-      --font-mono: ui-monospace, "SF Mono", "SFMono-Regular", Menlo, Consolas, "Liberation Mono", monospace;
-      --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-      --font-zh: "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
-    }
-
-    * { box-sizing: border-box; margin: 0; padding: 0; }
-
-    html { scroll-behavior: smooth; }
-
-    body {
-      background: var(--bg);
-      color: var(--text);
-      font-family: var(--font-sans);
-      line-height: 1.65;
-      -webkit-font-smoothing: antialiased;
-    }
-
-    /* Background grid */
-    body::before {
-      content: "";
-      position: fixed;
-      inset: 0;
-      background-image:
-        linear-gradient(rgba(77,171,247,0.03) 1px, transparent 1px),
-        linear-gradient(90deg, rgba(77,171,247,0.03) 1px, transparent 1px);
-      background-size: 60px 60px;
-      mask-image: radial-gradient(ellipse 80% 60% at 50% 0%, black 40%, transparent 100%);
-      pointer-events: none;
-      z-index: 0;
-    }
-
-    a { color: var(--accent); text-decoration: none; transition: color 0.15s; }
-    a:hover { color: #74c0fc; text-decoration: underline; }
-
-    .container {
-      max-width: 860px;
-      margin: 0 auto;
-      padding: 0 1.5rem;
-      position: relative;
-      z-index: 1;
-    }
-
-    /* Nav */
-    nav {
-      border-bottom: 1px solid var(--border);
-      background: rgba(10,14,20,0.75);
-      backdrop-filter: blur(12px) saturate(1.2);
-      position: sticky;
-      top: 0;
-      z-index: 20;
-    }
-    nav .container {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      height: 3.75rem;
-    }
-    .nav-brand {
-      font-weight: 700;
-      color: var(--text-bright);
-      font-family: var(--font-mono);
-      font-size: 0.95rem;
-      letter-spacing: -0.02em;
-    }
-    .nav-brand span { color: var(--accent); }
-    .nav-links {
-      display: flex;
-      align-items: center;
-      gap: 1.5rem;
-      list-style: none;
-      font-size: 0.875rem;
-      font-weight: 500;
-    }
-    .nav-links a { color: var(--text-muted); }
-    .nav-links a:hover { color: var(--text-bright); text-decoration: none; }
-    .lang-switch {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.35rem;
-      padding: 0.3rem 0.6rem;
-      border-radius: 6px;
-      border: 1px solid var(--border);
-      font-size: 0.8rem;
-      color: var(--text-muted);
-      transition: all 0.15s;
-    }
-    .lang-switch:hover {
-      border-color: var(--border-light);
-      color: var(--text-bright);
-      text-decoration: none;
-    }
-
-    /* Hero */
-    .hero {
-      padding: 5rem 0 3.5rem;
-      text-align: center;
-    }
-    .hero-badge {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.5rem;
-      padding: 0.35rem 0.9rem;
-      border-radius: 999px;
-      border: 1px solid var(--border);
-      background: var(--bg-elevated);
-      font-size: 0.8rem;
-      color: var(--text-muted);
-      margin-bottom: 1.5rem;
-    }
-    .hero-badge .dot {
-      width: 7px;
-      height: 7px;
-      border-radius: 50%;
-      background: var(--success);
-      box-shadow: 0 0 8px rgba(81,207,102,0.4);
-    }
-    .hero h1 {
-      font-family: var(--font-mono);
-      font-size: clamp(1.7rem, 4.5vw, 2.6rem);
-      color: var(--text-bright);
-      line-height: 1.2;
-      margin-bottom: 1.25rem;
-      letter-spacing: -0.02em;
-    }
-    .hero h1 .accent {
-      background: linear-gradient(135deg, var(--accent) 0%, #74c0fc 100%);
-      -webkit-background-clip: text;
-      -webkit-text-fill-color: transparent;
-      background-clip: text;
-    }
-    .hero .lead {
-      font-size: 1.15rem;
-      color: var(--text-muted);
-      max-width: 560px;
-      margin: 0 auto 2.5rem;
-      line-height: 1.6;
-    }
-
-    /* Terminal window */
-    .terminal {
-      max-width: 540px;
-      margin: 0 auto 2rem;
-      border-radius: 12px;
-      border: 1px solid var(--border-light);
-      background: #060a10;
-      overflow: hidden;
-      box-shadow:
-        0 0 0 1px rgba(77,171,247,0.08),
-        0 20px 50px -10px rgba(0,0,0,0.5),
-        0 0 80px -20px var(--accent-glow);
-    }
-    .terminal-header {
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-      padding: 0.65rem 1rem;
-      background: rgba(255,255,255,0.02);
-      border-bottom: 1px solid var(--border);
-    }
-    .terminal-header .win-dot {
-      width: 11px;
-      height: 11px;
-      border-radius: 50%;
-    }
-    .win-dot.red { background: #ff5f56; }
-    .win-dot.yellow { background: #ffbd2e; }
-    .win-dot.green { background: #27c93f; }
-    .terminal-header .title {
-      margin-left: 0.5rem;
-      font-size: 0.75rem;
-      color: var(--text-muted);
-      font-family: var(--font-mono);
-    }
-    .terminal-body {
-      padding: 1.1rem 1.25rem;
-      font-family: var(--font-mono);
-      font-size: 0.95rem;
-      color: var(--text-bright);
-      text-align: left;
-      display: flex;
-      align-items: center;
-      gap: 0.6rem;
-    }
-    .terminal-body .prompt { color: var(--success); }
-    .terminal-body .cursor {
-      display: inline-block;
-      width: 8px;
-      height: 1.15em;
-      background: var(--accent);
-      animation: blink 1s step-end infinite;
-      vertical-align: text-bottom;
-      margin-left: 2px;
-    }
-    @keyframes blink { 50% { opacity: 0; } }
-    .btn-copy {
-      margin-left: auto;
-      background: transparent;
-      color: var(--text-muted);
-      border: 1px solid var(--border);
-      border-radius: 6px;
-      padding: 0.3rem 0.7rem;
-      font-family: var(--font-sans);
-      font-size: 0.75rem;
-      font-weight: 600;
-      cursor: pointer;
-      transition: all 0.15s;
-      white-space: nowrap;
-    }
-    .btn-copy:hover {
-      border-color: var(--border-light);
-      color: var(--text-bright);
-    }
-    .btn-copy.copied {
-      border-color: var(--success);
-      color: var(--success);
-    }
-
-    .hero-actions {
-      display: flex;
-      gap: 0.75rem;
-      justify-content: center;
-      flex-wrap: wrap;
-    }
-    .btn {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.4rem;
-      padding: 0.6rem 1.2rem;
-      border-radius: 8px;
-      font-size: 0.9rem;
-      font-weight: 600;
-      transition: all 0.15s;
-      cursor: pointer;
-      border: none;
-    }
-    .btn-primary {
-      background: linear-gradient(135deg, var(--accent-dim) 0%, var(--accent) 100%);
-      color: #fff;
-      box-shadow: 0 4px 16px rgba(25,113,194,0.25);
-    }
-    .btn-primary:hover {
-      transform: translateY(-1px);
-      box-shadow: 0 6px 20px rgba(25,113,194,0.35);
-      text-decoration: none;
-      color: #fff;
-    }
-    .btn-secondary {
-      background: var(--bg-elevated);
-      color: var(--text);
-      border: 1px solid var(--border);
-    }
-    .btn-secondary:hover {
-      border-color: var(--border-light);
-      color: var(--text-bright);
-      text-decoration: none;
-    }
-
-    /* Screenshot */
-    .screenshot-wrap {
-      margin: 3rem 0;
-      border-radius: 14px;
-      overflow: hidden;
-      border: 1px solid var(--border);
-      background: var(--bg-card);
-      box-shadow: 0 30px 60px -20px rgba(0,0,0,0.6);
-    }
-    .screenshot-wrap img {
-      width: 100%;
-      height: auto;
-      display: block;
-    }
-
-    /* Sections */
-    section {
-      padding: 3rem 0;
-      border-top: 1px solid var(--border);
-    }
-    section h2 {
-      font-family: var(--font-mono);
-      font-size: 1.1rem;
-      color: var(--text-bright);
-      margin-bottom: 1.25rem;
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-    }
-    section h2 .icon {
-      color: var(--accent);
-    }
-    section p, section li {
-      color: var(--text-muted);
-      font-size: 0.95rem;
-      margin-bottom: 0.75rem;
-    }
-    section ul { padding-left: 1.25rem; }
-    section li { margin-bottom: 0.5rem; }
-    section li strong { color: var(--text); font-weight: 600; }
-
-    pre {
-      background: #060a10;
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      padding: 1rem 1.25rem;
-      overflow-x: auto;
-      font-family: var(--font-mono);
-      font-size: 0.82rem;
-      color: var(--text-bright);
-      margin: 0.75rem 0 1.25rem;
-      line-height: 1.6;
-    }
-    pre code { background: none; padding: 0; border: none; }
-    code {
-      font-family: var(--font-mono);
-      font-size: 0.88em;
-      background: var(--bg-elevated);
-      padding: 0.15rem 0.4rem;
-      border-radius: 4px;
-      border: 1px solid var(--border);
-      color: var(--text-bright);
-    }
-
-    /* Details / collapsible */
-    details {
-      background: var(--bg-card);
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      padding: 1rem 1.25rem;
-      margin-bottom: 0.75rem;
-    }
-    summary {
-      font-weight: 600;
-      color: var(--text-bright);
-      cursor: pointer;
-      user-select: none;
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-      font-size: 0.95rem;
-    }
-    summary::marker { display: none; }
-    details[open] summary { margin-bottom: 0.75rem; }
-    details pre { margin-bottom: 0; }
-
-    /* Feature grid */
-    .feature-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-      gap: 1rem;
-      margin-top: 1rem;
-    }
-    .feature-card {
-      background: var(--bg-card);
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      padding: 1.25rem;
-      transition: border-color 0.15s, transform 0.15s;
-    }
-    .feature-card:hover {
-      border-color: var(--border-light);
-      transform: translateY(-2px);
-    }
-    .feature-card h3 {
-      font-size: 0.9rem;
-      color: var(--text-bright);
-      margin-bottom: 0.4rem;
-      font-family: var(--font-mono);
-    }
-    .feature-card p {
-      font-size: 0.85rem;
-      margin: 0;
-      line-height: 1.55;
-    }
-
-    /* Footer */
-    footer {
-      border-top: 1px solid var(--border);
-      padding: 2.5rem 0 3.5rem;
-      text-align: center;
-      font-size: 0.85rem;
-      color: var(--text-muted);
-    }
-    footer .footer-links {
-      display: flex;
-      gap: 1.25rem;
-      justify-content: center;
-      flex-wrap: wrap;
-      margin-bottom: 1.25rem;
-      font-weight: 500;
-    }
-    .disclaimer {
-      font-style: italic;
-      opacity: 0.7;
-      margin-top: 0.75rem;
-    }
-
-    @media (max-width: 640px) {
-      .hero { padding: 3rem 0 2.5rem; }
-      .nav-links { gap: 0.9rem; font-size: 0.8rem; }
-      .terminal-body { font-size: 0.85rem; flex-wrap: wrap; }
-      .feature-grid { grid-template-columns: 1fr; }
-    }
-  </style>
-</head>
-<body>
-
-<nav>
-  <div class="container">
-    <div class="nav-brand">deepseek<span>-tui</span></div>
-    <ul class="nav-links">
-      <li><a href="#install">Install</a></li>
-      <li><a href="https://github.com/Hmbown/CodeWhale" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://github.com/Hmbown/CodeWhale/tree/main/docs" target="_blank" rel="noopener">Docs</a></li>
-      <li><a href="https://github.com/Hmbown/CodeWhale/issues" target="_blank" rel="noopener">Community</a></li>
-      <li><a href="./zh/" class="lang-switch" title="切换到简体中文">中</a></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="container">
-
-  <div class="hero" id="install">
-    <div class="hero-badge"><span class="dot"></span>v0.8.10 available now</div>
-    <h1>A terminal-native coding agent<br>for <span class="accent">DeepSeek&nbsp;V4</span></h1>
-    <p class="lead">1M-token context. Thinking-mode streaming. Single binary, zero dependencies — ships an MCP client, sandbox, and durable task queue out of the box.</p>
-
-    <div class="terminal">
-      <div class="terminal-header">
-        <span class="win-dot red"></span>
-        <span class="win-dot yellow"></span>
-        <span class="win-dot green"></span>
-        <span class="title">bash — zsh</span>
-      </div>
-      <div class="terminal-body">
-        <span class="prompt">$</span>
-        <span>npm i -g deepseek-tui</span>
-        <span class="cursor"></span>
-        <button class="btn-copy" onclick="copyInstall()" id="copyBtn">Copy</button>
-      </div>
-    </div>
-
-    <div class="hero-actions">
-      <a class="btn btn-primary" href="https://github.com/Hmbown/CodeWhale" target="_blank" rel="noopener">View on GitHub</a>
-      <a class="btn btn-secondary" href="https://github.com/sponsors/Hmbown" target="_blank" rel="noopener">Sponsor</a>
-    </div>
-  </div>
-
-  <div class="screenshot-wrap">
-    <img src="https://raw.githubusercontent.com/Hmbown/CodeWhale/main/assets/screenshot.png" alt="DeepSeek TUI screenshot" loading="lazy">
-  </div>
-
-  <section>
-    <h2><span class="icon">▸</span>What you get</h2>
-    <div class="feature-grid">
-      <div class="feature-card">
-        <h3>1M context</h3>
-        <p>Built for DeepSeek V4 with intelligent compaction and prefix-cache-aware cost optimization.</p>
-      </div>
-      <div class="feature-card">
-        <h3>Thinking stream</h3>
-        <p>Watch the model's chain-of-thought unfold in real time before the final answer arrives.</p>
-      </div>
-      <div class="feature-card">
-        <h3>Native RLM</h3>
-        <p>Fan out 1–16 cheap children in parallel for batched analysis and parallel reasoning.</p>
-      </div>
-      <div class="feature-card">
-        <h3>Full tool suite</h3>
-        <p>File ops, shell, git, web search, apply-patch, sub-agents, and MCP servers.</p>
-      </div>
-      <div class="feature-card">
-        <h3>Three modes</h3>
-        <p>Plan (read-only), Agent (interactive), and YOLO (auto-approved) for any workflow.</p>
-      </div>
-      <div class="feature-card">
-        <h3>Durable sessions</h3>
-        <p>Save, resume, and rollback workspace state without touching your repo's .git.</p>
-      </div>
-    </div>
-  </section>
-
-  <section id="china">
-    <h2><span class="icon">◎</span>China / mirror-friendly install</h2>
-    <p>If downloads from GitHub or npm are slow from mainland China, use one of these paths:</p>
-
-    <details open>
-      <summary>npm via 淘宝镜像 (fastest)</summary>
-      <pre><code>npm config set registry https://registry.npmmirror.com
-npm install -g deepseek-tui</code></pre>
-      <p style="font-size:0.85rem;margin-bottom:0;">The npm wrapper itself will still download the binary from GitHub Releases during <code>postinstall</code>. If that step is slow, set a mirror for the binary download:</p>
-      <pre style="margin-top:0.5rem;margin-bottom:0;"><code>DEEPSEEK_TUI_RELEASE_BASE_URL=https://your-mirror.example.com \
-  npm install -g deepseek-tui</code></pre>
-    </details>
-
-    <details>
-      <summary>Cargo via 清华 TUNA mirror</summary>
-      <p>Add to <code>~/.cargo/config.toml</code>:</p>
-      <pre><code>[source.crates-io]
-replace-with = "tuna"
-
-[source.tuna]
-registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"</code></pre>
-      <p>Then install both binaries:</p>
-      <pre><code>cargo install deepseek-tui-cli --locked   # provides `deepseek`
-cargo install deepseek-tui     --locked   # provides `deepseek-tui`
-deepseek --version</code></pre>
-    </details>
-
-    <details>
-      <summary>Rustup mirror (for building from source)</summary>
-      <pre><code>export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
-export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code></pre>
-    </details>
-
-    <p style="margin-top:1rem;font-size:0.875rem;">Full platform guide: <a href="https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md" target="_blank" rel="noopener">docs/INSTALL.md</a> · <a href="../README.zh-CN.md">简体中文 README</a></p>
-  </section>
-
-</main>
-
-<footer>
-  <div class="container">
-    <div class="footer-links">
-      <a href="https://github.com/Hmbown/CodeWhale" target="_blank" rel="noopener">GitHub</a>
-      <a href="https://github.com/Hmbown/CodeWhale/tree/main/docs" target="_blank" rel="noopener">Docs</a>
-      <a href="https://github.com/Hmbown/CodeWhale/issues" target="_blank" rel="noopener">Issues</a>
-      <a href="https://github.com/sponsors/Hmbown" target="_blank" rel="noopener">Sponsor</a>
-      <a href="mailto:security@deepseek-tui.com">Security</a>
-    </div>
-    <p class="disclaimer">Not affiliated with DeepSeek Inc.</p>
-    <p style="margin-top:0.75rem;">&copy; DeepSeek TUI contributors. MIT License.</p>
-  </div>
-</footer>
-
-<script>
-  function copyInstall() {
-    navigator.clipboard.writeText('npm i -g deepseek-tui').then(() => {
-      const btn = document.getElementById('copyBtn');
-      btn.textContent = 'Copied';
-      btn.classList.add('copied');
-      setTimeout(() => { btn.textContent = 'Copy'; btn.classList.remove('copied'); }, 1800);
-    });
-  }
-</script>
-
-</body>
-</html>
diff --git a/website/zh/index.html b/website/zh/index.html
deleted file mode 100644
index 2db6209b..00000000
--- a/website/zh/index.html
+++ /dev/null
@@ -1,575 +0,0 @@
-<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>DeepSeek TUI — 终端原生编程智能体</title>
-  <link rel="alternate" hreflang="en" href="../">
-  <style>
-    :root {
-      --bg: #0a0e14;
-      --bg-elevated: #111820;
-      --bg-card: #0f151c;
-      --border: #1e2a36;
-      --border-light: #263545;
-      --text: #b8c5d6;
-      --text-muted: #5e7a94;
-      --text-bright: #e8f0f8;
-      --accent: #4dabf7;
-      --accent-dim: #1971c2;
-      --accent-glow: rgba(77, 171, 247, 0.15);
-      --success: #51cf66;
-      --warning: #ffd43b;
-      --font-mono: ui-monospace, "SF Mono", "SFMono-Regular", Menlo, Consolas, "Liberation Mono", monospace;
-      --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
-    }
-
-    * { box-sizing: border-box; margin: 0; padding: 0; }
-
-    html { scroll-behavior: smooth; }
-
-    body {
-      background: var(--bg);
-      color: var(--text);
-      font-family: var(--font-sans);
-      line-height: 1.75;
-      -webkit-font-smoothing: antialiased;
-    }
-
-    body::before {
-      content: "";
-      position: fixed;
-      inset: 0;
-      background-image:
-        linear-gradient(rgba(77,171,247,0.03) 1px, transparent 1px),
-        linear-gradient(90deg, rgba(77,171,247,0.03) 1px, transparent 1px);
-      background-size: 60px 60px;
-      mask-image: radial-gradient(ellipse 80% 60% at 50% 0%, black 40%, transparent 100%);
-      pointer-events: none;
-      z-index: 0;
-    }
-
-    a { color: var(--accent); text-decoration: none; transition: color 0.15s; }
-    a:hover { color: #74c0fc; text-decoration: underline; }
-
-    .container {
-      max-width: 860px;
-      margin: 0 auto;
-      padding: 0 1.5rem;
-      position: relative;
-      z-index: 1;
-    }
-
-    nav {
-      border-bottom: 1px solid var(--border);
-      background: rgba(10,14,20,0.75);
-      backdrop-filter: blur(12px) saturate(1.2);
-      position: sticky;
-      top: 0;
-      z-index: 20;
-    }
-    nav .container {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      height: 3.75rem;
-    }
-    .nav-brand {
-      font-weight: 700;
-      color: var(--text-bright);
-      font-family: var(--font-mono);
-      font-size: 0.95rem;
-      letter-spacing: -0.02em;
-    }
-    .nav-brand span { color: var(--accent); }
-    .nav-links {
-      display: flex;
-      align-items: center;
-      gap: 1.5rem;
-      list-style: none;
-      font-size: 0.875rem;
-      font-weight: 500;
-    }
-    .nav-links a { color: var(--text-muted); }
-    .nav-links a:hover { color: var(--text-bright); text-decoration: none; }
-    .lang-switch {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.35rem;
-      padding: 0.3rem 0.6rem;
-      border-radius: 6px;
-      border: 1px solid var(--border);
-      font-size: 0.8rem;
-      color: var(--text-muted);
-      transition: all 0.15s;
-    }
-    .lang-switch:hover {
-      border-color: var(--border-light);
-      color: var(--text-bright);
-      text-decoration: none;
-    }
-
-    .hero {
-      padding: 5rem 0 3.5rem;
-      text-align: center;
-    }
-    .hero-badge {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.5rem;
-      padding: 0.35rem 0.9rem;
-      border-radius: 999px;
-      border: 1px solid var(--border);
-      background: var(--bg-elevated);
-      font-size: 0.8rem;
-      color: var(--text-muted);
-      margin-bottom: 1.5rem;
-    }
-    .hero-badge .dot {
-      width: 7px;
-      height: 7px;
-      border-radius: 50%;
-      background: var(--success);
-      box-shadow: 0 0 8px rgba(81,207,102,0.4);
-    }
-    .hero h1 {
-      font-family: var(--font-mono);
-      font-size: clamp(1.6rem, 4.5vw, 2.4rem);
-      color: var(--text-bright);
-      line-height: 1.3;
-      margin-bottom: 1.25rem;
-      letter-spacing: -0.02em;
-    }
-    .hero h1 .accent {
-      background: linear-gradient(135deg, var(--accent) 0%, #74c0fc 100%);
-      -webkit-background-clip: text;
-      -webkit-text-fill-color: transparent;
-      background-clip: text;
-    }
-    .hero .lead {
-      font-size: 1.1rem;
-      color: var(--text-muted);
-      max-width: 560px;
-      margin: 0 auto 2.5rem;
-      line-height: 1.7;
-    }
-
-    .terminal {
-      max-width: 540px;
-      margin: 0 auto 2rem;
-      border-radius: 12px;
-      border: 1px solid var(--border-light);
-      background: #060a10;
-      overflow: hidden;
-      box-shadow:
-        0 0 0 1px rgba(77,171,247,0.08),
-        0 20px 50px -10px rgba(0,0,0,0.5),
-        0 0 80px -20px var(--accent-glow);
-    }
-    .terminal-header {
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-      padding: 0.65rem 1rem;
-      background: rgba(255,255,255,0.02);
-      border-bottom: 1px solid var(--border);
-    }
-    .terminal-header .win-dot {
-      width: 11px;
-      height: 11px;
-      border-radius: 50%;
-    }
-    .win-dot.red { background: #ff5f56; }
-    .win-dot.yellow { background: #ffbd2e; }
-    .win-dot.green { background: #27c93f; }
-    .terminal-header .title {
-      margin-left: 0.5rem;
-      font-size: 0.75rem;
-      color: var(--text-muted);
-      font-family: var(--font-mono);
-    }
-    .terminal-body {
-      padding: 1.1rem 1.25rem;
-      font-family: var(--font-mono);
-      font-size: 0.95rem;
-      color: var(--text-bright);
-      text-align: left;
-      display: flex;
-      align-items: center;
-      gap: 0.6rem;
-    }
-    .terminal-body .prompt { color: var(--success); }
-    .terminal-body .cursor {
-      display: inline-block;
-      width: 8px;
-      height: 1.15em;
-      background: var(--accent);
-      animation: blink 1s step-end infinite;
-      vertical-align: text-bottom;
-      margin-left: 2px;
-    }
-    @keyframes blink { 50% { opacity: 0; } }
-    .btn-copy {
-      margin-left: auto;
-      background: transparent;
-      color: var(--text-muted);
-      border: 1px solid var(--border);
-      border-radius: 6px;
-      padding: 0.3rem 0.7rem;
-      font-family: var(--font-sans);
-      font-size: 0.75rem;
-      font-weight: 600;
-      cursor: pointer;
-      transition: all 0.15s;
-      white-space: nowrap;
-    }
-    .btn-copy:hover {
-      border-color: var(--border-light);
-      color: var(--text-bright);
-    }
-    .btn-copy.copied {
-      border-color: var(--success);
-      color: var(--success);
-    }
-
-    .hero-actions {
-      display: flex;
-      gap: 0.75rem;
-      justify-content: center;
-      flex-wrap: wrap;
-    }
-    .btn {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.4rem;
-      padding: 0.6rem 1.2rem;
-      border-radius: 8px;
-      font-size: 0.9rem;
-      font-weight: 600;
-      transition: all 0.15s;
-      cursor: pointer;
-      border: none;
-    }
-    .btn-primary {
-      background: linear-gradient(135deg, var(--accent-dim) 0%, var(--accent) 100%);
-      color: #fff;
-      box-shadow: 0 4px 16px rgba(25,113,194,0.25);
-    }
-    .btn-primary:hover {
-      transform: translateY(-1px);
-      box-shadow: 0 6px 20px rgba(25,113,194,0.35);
-      text-decoration: none;
-      color: #fff;
-    }
-    .btn-secondary {
-      background: var(--bg-elevated);
-      color: var(--text);
-      border: 1px solid var(--border);
-    }
-    .btn-secondary:hover {
-      border-color: var(--border-light);
-      color: var(--text-bright);
-      text-decoration: none;
-    }
-
-    .screenshot-wrap {
-      margin: 3rem 0;
-      border-radius: 14px;
-      overflow: hidden;
-      border: 1px solid var(--border);
-      background: var(--bg-card);
-      box-shadow: 0 30px 60px -20px rgba(0,0,0,0.6);
-    }
-    .screenshot-wrap img {
-      width: 100%;
-      height: auto;
-      display: block;
-    }
-
-    section {
-      padding: 3rem 0;
-      border-top: 1px solid var(--border);
-    }
-    section h2 {
-      font-family: var(--font-mono);
-      font-size: 1.1rem;
-      color: var(--text-bright);
-      margin-bottom: 1.25rem;
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-    }
-    section h2 .icon { color: var(--accent); }
-    section p, section li {
-      color: var(--text-muted);
-      font-size: 0.95rem;
-      margin-bottom: 0.75rem;
-    }
-    section ul { padding-left: 1.25rem; }
-    section li { margin-bottom: 0.5rem; }
-    section li strong { color: var(--text); font-weight: 600; }
-
-    pre {
-      background: #060a10;
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      padding: 1rem 1.25rem;
-      overflow-x: auto;
-      font-family: var(--font-mono);
-      font-size: 0.82rem;
-      color: var(--text-bright);
-      margin: 0.75rem 0 1.25rem;
-      line-height: 1.6;
-    }
-    pre code { background: none; padding: 0; border: none; }
-    code {
-      font-family: var(--font-mono);
-      font-size: 0.88em;
-      background: var(--bg-elevated);
-      padding: 0.15rem 0.4rem;
-      border-radius: 4px;
-      border: 1px solid var(--border);
-      color: var(--text-bright);
-    }
-
-    details {
-      background: var(--bg-card);
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      padding: 1rem 1.25rem;
-      margin-bottom: 0.75rem;
-    }
-    summary {
-      font-weight: 600;
-      color: var(--text-bright);
-      cursor: pointer;
-      user-select: none;
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-      font-size: 0.95rem;
-    }
-    summary::marker { display: none; }
-    details[open] summary { margin-bottom: 0.75rem; }
-    details pre { margin-bottom: 0; }
-
-    .feature-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-      gap: 1rem;
-      margin-top: 1rem;
-    }
-    .feature-card {
-      background: var(--bg-card);
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      padding: 1.25rem;
-      transition: border-color 0.15s, transform 0.15s;
-    }
-    .feature-card:hover {
-      border-color: var(--border-light);
-      transform: translateY(-2px);
-    }
-    .feature-card h3 {
-      font-size: 0.9rem;
-      color: var(--text-bright);
-      margin-bottom: 0.4rem;
-      font-family: var(--font-mono);
-    }
-    .feature-card p {
-      font-size: 0.85rem;
-      margin: 0;
-      line-height: 1.55;
-    }
-
-    footer {
-      border-top: 1px solid var(--border);
-      padding: 2.5rem 0 3.5rem;
-      text-align: center;
-      font-size: 0.85rem;
-      color: var(--text-muted);
-    }
-    footer .footer-links {
-      display: flex;
-      gap: 1.25rem;
-      justify-content: center;
-      flex-wrap: wrap;
-      margin-bottom: 1.25rem;
-      font-weight: 500;
-    }
-    .disclaimer {
-      font-style: italic;
-      opacity: 0.7;
-      margin-top: 0.75rem;
-    }
-
-    @media (max-width: 640px) {
-      .hero { padding: 3rem 0 2.5rem; }
-      .nav-links { gap: 0.9rem; font-size: 0.8rem; }
-      .terminal-body { font-size: 0.85rem; flex-wrap: wrap; }
-      .feature-grid { grid-template-columns: 1fr; }
-    }
-  </style>
-</head>
-<body>
-
-<nav>
-  <div class="container">
-    <div class="nav-brand">deepseek<span>-tui</span></div>
-    <ul class="nav-links">
-      <li><a href="#install">安装</a></li>
-      <li><a href="https://github.com/Hmbown/CodeWhale" target="_blank" rel="noopener">GitHub</a></li>
-      <li><a href="https://github.com/Hmbown/CodeWhale/tree/main/docs" target="_blank" rel="noopener">文档</a></li>
-      <li><a href="https://github.com/Hmbown/CodeWhale/issues" target="_blank" rel="noopener">社区</a></li>
-      <li><a href="../" class="lang-switch" title="Switch to English">EN</a></li>
-    </ul>
-  </div>
-</nav>
-
-<main class="container">
-
-  <div class="hero" id="install">
-    <div class="hero-badge"><span class="dot"></span>v0.8.10 现已发布</div>
-    <h1>面向 <span class="accent">DeepSeek&nbsp;V4</span><br>的终端原生编程智能体</h1>
-    <p class="lead">100 万 token 上下文。思考模式推理流。单一二进制，零依赖——开箱自带 MCP 客户端、沙箱和持久化任务队列。</p>
-
-    <div class="terminal">
-      <div class="terminal-header">
-        <span class="win-dot red"></span>
-        <span class="win-dot yellow"></span>
-        <span class="win-dot green"></span>
-        <span class="title">bash — zsh</span>
-      </div>
-      <div class="terminal-body">
-        <span class="prompt">$</span>
-        <span>npm i -g deepseek-tui</span>
-        <span class="cursor"></span>
-        <button class="btn-copy" onclick="copyInstall()" id="copyBtn">复制</button>
-      </div>
-    </div>
-
-    <div class="hero-actions">
-      <a class="btn btn-primary" href="https://github.com/Hmbown/CodeWhale" target="_blank" rel="noopener">在 GitHub 上查看</a>
-      <a class="btn btn-secondary" href="https://github.com/sponsors/Hmbown" target="_blank" rel="noopener">GitHub 赞助</a>
-    </div>
-  </div>
-
-  <div class="screenshot-wrap">
-    <img src="https://raw.githubusercontent.com/Hmbown/CodeWhale/main/assets/screenshot.png" alt="DeepSeek TUI 截图" loading="lazy">
-  </div>
-
-  <section>
-    <h2><span class="icon">▸</span>核心功能</h2>
-    <div class="feature-grid">
-      <div class="feature-card">
-        <h3>100 万上下文</h3>
-        <p>为 DeepSeek V4 构建，支持智能压缩和前缀缓存感知成本优化。</p>
-      </div>
-      <div class="feature-card">
-        <h3>思考流式输出</h3>
-        <p>实时观察模型思维链展开，在最终答案到达前看到推理过程。</p>
-      </div>
-      <div class="feature-card">
-        <h3>原生 RLM</h3>
-        <p>并行调度 1–16 个低成本子任务，用于批量分析和并行推理。</p>
-      </div>
-      <div class="feature-card">
-        <h3>完整工具集</h3>
-        <p>文件操作、Shell、Git、网页搜索、补丁应用、子智能体和 MCP 服务器。</p>
-      </div>
-      <div class="feature-card">
-        <h3>三种模式</h3>
-        <p>Plan（只读探索）、Agent（交互审批）、YOLO（自动批准），适配任意工作流。</p>
-      </div>
-      <div class="feature-card">
-        <h3>持久化会话</h3>
-        <p>保存、恢复、回滚工作区状态，不影响项目自身的 .git 仓库。</p>
-      </div>
-    </div>
-  </section>
-
-  <section id="china">
-    <h2><span class="icon">◎</span>中国大陆镜像安装指南</h2>
-    <p>如果从 GitHub 或 npm 下载较慢，请按以下方式选择最适合你的安装路径：</p>
-
-    <details open>
-      <summary>npm + 淘宝镜像（推荐，最简单）</summary>
-      <p>设置 npm 镜像后全局安装：</p>
-      <pre><code>npm config set registry https://registry.npmmirror.com
-npm install -g deepseek-tui</code></pre>
-      <p>npm 包在安装时会通过 <code>postinstall</code> 从 GitHub Releases 下载对应平台的二进制文件。如果这一步也很慢，可以设置二进制下载镜像地址：</p>
-      <pre><code>DEEPSEEK_TUI_RELEASE_BASE_URL=https://your-mirror.example.com \
-  npm install -g deepseek-tui</code></pre>
-    </details>
-
-    <details>
-      <summary>Cargo + 清华 TUNA 镜像</summary>
-      <p>在 <code>~/.cargo/config.toml</code> 中添加镜像配置：</p>
-      <pre><code>[source.crates-io]
-replace-with = "tuna"
-
-[source.tuna]
-registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"</code></pre>
-      <p>然后安装两个二进制文件（调度器在运行时会自动调用 TUI）：</p>
-      <pre><code>cargo install deepseek-tui-cli --locked   # 提供入口命令 deepseek
-cargo install deepseek-tui     --locked   # 提供交互式 TUI 二进制
-deepseek --version</code></pre>
-    </details>
-
-    <details>
-      <summary>从源码构建（Rustup 镜像）</summary>
-      <p>如果还没有安装 Rust，先通过清华镜像安装 rustup：</p>
-      <pre><code>export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
-export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code></pre>
-      <p>配置 Cargo 镜像后从源码构建：</p>
-      <pre><code>git clone https://github.com/Hmbown/CodeWhale.git
-cd CodeWhale
-cargo install --path crates/cli --locked
-cargo install --path crates/tui --locked</code></pre>
-    </details>
-
-    <details>
-      <summary>手动下载预编译二进制</summary>
-      <p>直接从 GitHub Releases 下载对应平台的二进制文件，放到 <code>PATH</code> 目录即可：</p>
-      <pre><code>mkdir -p ~/.local/bin
-curl -L -o ~/.local/bin/deepseek \
-  https://github.com/Hmbown/CodeWhale/releases/latest/download/deepseek-linux-x64
-curl -L -o ~/.local/bin/deepseek-tui \
-  https://github.com/Hmbown/CodeWhale/releases/latest/download/deepseek-tui-linux-x64
-chmod +x ~/.local/bin/deepseek ~/.local/bin/deepseek-tui</code></pre>
-      <p>macOS 用户将 <code>linux-x64</code> 替换为 <code>macos-arm64</code> 或 <code>macos-x64</code>，并将 <code>sha256sum</code> 替换为 <code>shasum -a 256</code>。</p>
-    </details>
-
-    <p style="margin-top:1rem;font-size:0.875rem;">完整平台安装指南：<a href="https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md" target="_blank" rel="noopener">docs/INSTALL.md</a> · <a href="../../README.zh-CN.md">简体中文 README</a></p>
-  </section>
-
-</main>
-
-<footer>
-  <div class="container">
-    <div class="footer-links">
-      <a href="https://github.com/Hmbown/CodeWhale" target="_blank" rel="noopener">GitHub</a>
-      <a href="https://github.com/Hmbown/CodeWhale/tree/main/docs" target="_blank" rel="noopener">文档</a>
-      <a href="https://github.com/Hmbown/CodeWhale/issues" target="_blank" rel="noopener">Issues</a>
-      <a href="https://github.com/sponsors/Hmbown" target="_blank" rel="noopener">GitHub 赞助</a>
-      <a href="mailto:security@deepseek-tui.com">安全</a>
-    </div>
-    <p class="disclaimer">本项目与 DeepSeek Inc. 无隶属关系。</p>
-    <p style="margin-top:0.75rem;">&copy; DeepSeek TUI contributors. MIT License.</p>
-  </div>
-</footer>
-
-<script>
-  function copyInstall() {
-    navigator.clipboard.writeText('npm i -g deepseek-tui').then(() => {
-      const btn = document.getElementById('copyBtn');
-      btn.textContent = '已复制';
-      btn.classList.add('copied');
-      setTimeout(() => { btn.textContent = '复制'; btn.classList.remove('copied'); }, 1800);
-    });
-  }
-</script>
-
-</body>
-</html>